!==============================================================================! ! GARFIELD, A drift-chamber simulation program, HELP file. ! ! ! ! This file describes the Garfield commands in detail, it does not provide ! ! information on the way the program should be started. ! ! ! ! To be converted to a help library via the following commands: ! ! ! ! On a Vax, when in DCL: ! ! $ librarian/create/help garfield garfield ! ! $ set file/truncate garfield.hlb (to save some space) ! ! ! ! On all computers, when in Garfield: ! ! % pack-help-file ! ! ! ! Vax details: ! ! The logical HELP$GARFIELD should be defined as the full name (i.e. including ! ! disk and directory) of your GARFIELD.HLB. The program opens the help library ! ! by reference to the logical rather than an file name. The logical is usually ! ! defined by the front-end program, GARFRUN.EXE. ! ! ! ! The advice from Carlo Mekenkamp / Rijks Universiteit Leiden is gratefully ! ! acknowledged. He also contributed the Vax-Fortran routine calling VMS HELP. ! ! ! ! This file corresponds to Garfield version 7.39. ! ! ! ! Copyright: Rob Veenhof, 2011. ! !==============================================================================! 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 !Welaborate examples have been contributed by various users. !WThese programs can be run, without need for compilation, on most of the central CERN computers. Garfield input is subdivided in sections: !Wul_start - the "-> &CELL" section: chamber layout, ANSYS, Maxwell and Tosca interfaces; - the "-> &MAGNETIC" section: setting the magnetic field; - the "-> &GAS" section: transport and ionisation properties of the gas and the interfaces to Heed and Magboltz; - the "-> &OPTIMISE" section: modification of the layout, space charge and improving the field uniformity; - the "-> &FIELD" section: visualisation of the field; - the "-> &DRIFT" section: drifting of electrons and ions; - the "-> &SIGNAL" section: induced currents; - top level input can be entered after a "-> &MAIN" command; - program execution ends when "-> &STOP" is entered. !Wul_end Garfield input can also contain rudimentary scripting: !Wul_start - "-> Call"ing procedures; - "-> Do" loops to repeatedly execute statements; - "-> Global" and "-> Vector" to manipulate variables; - "-> If_line" and "-> If_block" for conditional execution of statements; - "-> Parse" to obtain terminal input while running an input file; - "-> Say" for simple output. !Wul_end Occasionally, you may wish to use the various utilities: !Wul_start - background to the "-> algebra" used to evaluate formulae; - "-> comment" in input files; - use of the "-> control_keys"; - "-> error_handling" in program library procedures; - enhanced control of "-> graphics"; - "-> input" from, "-> output" to and manipulation of "-> dataset"s; - "-> OPTIONS" valid in all sections; - "-> recording" terminal input; - issuing "-> shell" commands; - "-> translation" of characters in input statements. !Wul_end 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). !D16 The help facility you are in at present is the normal Vax HELP on Vax computers and something closely resembling it on other machines. You can obtain further information by typing one of the items listed under "additional information". A return without input will take you back by one level. Wildcards are permitted: P* will match both PLANE and PERIODICITY, an asterisk at the end is always assumed. A question mark as only input will cause the list of alternatives to be redisplayed. This help file can also be read via WWW at the address: http://cern.ch/garfield/help Examples of the use of the program can be found at: http://cern.ch/garfield/examples Information on the command line format of these programs can be found in http://cern.ch/garfield/command/command.html 2 getting_started ! If this is the first time you use the program, get a copy of the ! printed manual that corresponds to the version you'll be using. ! You can obtain one from the program library office at CERN (Lysiane ! Besson) or from the author. The manual can also be consulted via ! WWW, the URL is currently http://cern.ch/garfield. ! 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: !W
  "-> &CELL"
  "-> &CELL -> plane" x -1
  plane y -1
  "-> &CELL -> rows"
  S 5 * i i 1000*i

  "-> &FIELD"
  "-> &FIELD -> plot-field" surface V, contour V
!W
The program is structured in a set of so-called sections (cell, gas, magnetic, optimise, field, drift and signal) that each contain a set of instructions performing certain tasks. The cell section e.g. will read the cell description, the field section offers facilities for plotting the field etc. The sections are headed by a line starting with an ampersand (&), "-> &CELL" and "-> &FIELD" start sections in the above example. You may insert one or more blanks between the & and the section name. There is one special header: "-> &STOP" (or &QUIT or &EXIT if you prefer) which will stop program execution. End-Of-File on input will have the same effect. The instructions within the sections are free format lines. Input files can be both fixed and variable record length. The maximum record length is large, about 500\ characters. An ellipsis (...) at the end of one physical line indicates that the instruction continues on the next. There can be only 1 instruction per input line. The first word on each line is the command proper. The other words can be viewed as a set of parameters, with sometimes a value assigned to them. The elements on the input are separated from each other by a blank ( ), a comma (,), a colon (:) or an equal sign (=). There is no difference in meaning between these "-> introduction -> separators". You may if you wish place several between the words. Case is irrelevant in commands. Strings of which the case matters, such as "-> dataset -> structure -> file" names on Unix systems and also in identifiers, should be delimited by double "-> introduction -> quotes". Here is an example of a cell description: !W
  "-> &CELL"
  "-> &CELL -> plane" x=10, V=1000
  plane x -10 ...
        V 1000
  "-> &CELL -> periodicity" y 3
  "-> &CELL -> rows"
  S * * 0 0 5000

  "-> &CELL -> cell-identifier" "Test cell"
!W
The words "-> &CELL -> PLANE", "-> &CELL -> PERIODICITY", "-> &CELL -> ROWS" and "-> &CELL -> CELL-IDENTIFIER" are the commands. The command "PLANE" has two arguments with a value for each. You may if you wish invert their order without affecting the meaning of the command: !W
  PLANE V=1000 X=10
!W
This is true in general - exceptions are explicitly stated. PLANE, like most commands, can have more arguments. If no value is given, defaults are used for these, if a meaningful default is available. The ROWS command has a slightly different syntax from the rest: apart from having arguments of its own (not shown in the example), it is followed by a series of lines (1 in this example) that contain the actual data. The end of the list is signalled by a blank line. There is one more such command in the cell section ("-> &CELL -> SOLIDS") and there are also a few commands of this type in the gas section ("-> &GAS -> CLUSTER" and "-> &GAS -> TABLE"). Nearly all words in the input may be abbreviated to some extent in each of the 'segments': !W
  E-MOST-PROBABLE    & CELL      PLANE
  E-MOST-PROB        &CELL       PLAN
  E-M-PROB           &C          PL
!W
Garfield does not pretend to be programmable, but "-> Do" loops and conditional execution of statements ("-> If_line"s and "-> If_block"s) exist. For clarity, all control statements are shown with initial capital in the documentation. Here is an example: !W
  "-> 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."
        "-> Do -> Iterate"
     Elseif "-> algebra -> functions -> entier"(n)#n Then
        "-> Say" "The number you entered, {n}, is not an integer"
        "-> Do -> 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
!W
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. 2 command_descriptions The syntax conventions used in the command descriptions are: !Wdl_start !T+ + ------------------------------------------------------------------- Syntax element Description ------------------------------------------------------------------- { a | b ... } One, and only one, of the items between the brackets must be present. If the item is omitted, the command as a whole will be declared as not valid. The curly brackets are not part of the command, they are only typed when "-> algebra -> variables -> substitution" of expressions of global variables is desired. [ a | b ... ] You may select one, and not more than one. item from the list between brackets, but you don't have to. A default value will be used if you omit this item. The square brackets are not part of the command, such brackets are only typed when indexing a "-> algebra -> variables -> types -> 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). ------------------------------------------------------------------- !Wdl_end 2 input_elements The following rules concerning the input should be observed: !Wdl_start !T+ + ------------------------------------------------------------------- Input element Description ------------------------------------------------------------------- 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 "-> introduction -> brackets" which serve entirely different purposes. case Matters for file names on Unix and VM/CMS systems. By default all input is converted to upper case when reading the command, but this can be avoided by using quotes. defaults Default arguments are chosen by typing an asterisk. long commands A line that is to be continued on the next line should end in ... (ellipsis), there is no limit on the number of continuation lines by itself but the total length of a line shouldn't exceed some fixed number (at present 500). separators Words in the input lines must be separated by one or more of the "-> introduction -> separators". quotes Like with brackets, care should be taken to use the various "-> introduction -> quotes" correctly. ------------------------------------------------------------------- !Wdl_end 2 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. !Wtable_start !T+P + +P . ------------------------------------------------------------------- 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 @ ------------------------------------------------------------------- !Wtable_end Some characters have a special meaning when used inside commands: !Wtable_start !T+P + +P . --------------------------------------------------------------------- Character Description Example --------------------------------------------------------------------- * Default value AREA * -2 * 2 * Wildcard GET CELL.DAT PL* @ Enter the algebra editor PLOT CONT @ HIST E !D1 \ Escape character \{abc\} !R\\ Escape character \\{abc\\} !D2 ... Continuation lines PLANE X ... 2, V=1000 !R... 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 --------------------------------------------------------------------- !Wtable_end 2 brackets Three kinds of parentheses are used in Garfield. One of them, the curly bracket, is very often misused. !Wul_start - Round brackets "( ... )": Used in formulae, for arguments of "-> algebra -> functions" and procedures, and also around sub-expressions that need to be evaluated first. Examples: !W
    "-> Global" a=cos(2*pi/3)
    "-> Call" "-> Call -> print"(1+2*(3+4))
!W
- Square brackets "[ ... ]": Used in formulae, when indexing a "-> algebra -> variables -> types -> Matrix". Example: !W
    Global a="-> algebra -> functions -> number"(b[3;3])
!W
- Curly brackets "{ ... }": Form the bridge between normal statements and "-> Global" variables. Curly brackets request evaluation of what is between the brackets followed by "-> algebra -> variables -> substitution" of the result in the input statement. !W
Curly brackets must not be used in control statements. !W
Example: !W
    Global argon=80
    Global co2=20
    Global gas_file=`Ar`/"-> algebra -> functions -> string"(argon)/`CO2`/string(co2)
    Call "-> Call -> inquire_file"(gas_file, exist)
    If exist Then
       get {gas_file}
    Else
       magboltz argon {argon} co2 {co2}
       heed argon {argon} co2 {co2}
       add mobility 1.5e-6
       write {gas_file}
    Endif
!W
Please note that curly brackets are used only in the "-> &GAS -> GET", "-> &GAS -> WRITE", "-> &GAS -> MAGBOLTZ" and "-> &GAS -> HEED" statements - these are commands, not control statements. Curly brackets are not used when the global variable GAS_FILE is used as argument of the "-> Call -> INQUIRE_FILE" procedure. Similarly, EXIST is not enclosed in curly brackets in the If-condition. When ARGON and CO2 are used without brackets in the "-> Global" statement, but with curly brackets in MAGBOLTZ and Heed. !Wul_end 2 quotes Three kinds of quotes are used in Garfield. Please use them correctly !!! !Wul_start - Double quote ("): Is used in normal input statements, around strings that need to form a single input word but that contain special characters such as spaces, equal signs, commata, double quotes etc. Case is preserved between double quotes. Examples: !W
    Say "Hello, how are you doing ?"
    arrival dataset "arrival.dat"
!W
- Single quote ('): Are like double quotes, but the text between single quotes is converted to upper case. Example: !W
    Call threshold_crossing(1,-0.02,`rising,linear`,n,t1,t2)
    If 'n=0' Then 
       Say "Warning: No crossing found."
       Iterate
    Endif
!W
In earlier versions of Garfield, the condition of "-> If_line"s and "-> If_block"s had to be a single word in upper case. In the example, an equal sign is used in the condition. Since equal signs are "-> introduction -> separators", like commata and blanks, the condition without quotes would be read as 2 words: "N" and "0". - Reverse quote (`): Are used to delimit "-> algebra -> variables -> types -> String"s. They appear only in control statements such as "-> Call", "-> Global", "-> If_line", "-> If_block", "-> Do" and "-> Parse". Example: !W
    Global argon=80
    Global co2=20
    Global gas_file=`Ar`/"-> algebra -> functions -> string"(argon)/`CO2`/string(co2)
!W
A file name is constructed from the percentages of Ar and CO\2\. !Wul_end 2 separators The following characters act as word separators in Garfield: !Wul_start - comma: "," - blank: " " - equal sign: "=" - colon: ":" !Wul_end Text strings, such as formulae, that should not be broken up but which contain a word separator, should be put between single or double "-> introduction -> quotes". The string is converted to upper case when single quotes are used, while the case is preserved with double quotes. 2 trouble You are urged to always check the results you obtain with Garfield make sense. It is remarkably easy to obtain incorrect results by using inappropriate parameter settings. Furthermore, the presence of accidental errors in the Garfield program is guaranteed. Garfield is a fairly large drift chamber simulation program, it is a one person enterprise and the program changes rapidly. This has the advantage for the user that the program tries to track changes in the design considerations of gas detectors. The drawback is a lack of (complete) backwards compatibility of input files. Please contact the author in case of trouble and if you need further information, have suggestions for extensions etc. In case you suspect an error, send the following: !Wul_start * a complete copy of the input, not just the relevant part * a complete copy of the output, not just the relevant part * a description of the system you are running on plus version indication of the program. !Wul_end 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: !W
  http://cern.ch/garfield/cnl       for modifications
  http://cern.ch/garfield/examples  for examples
  http://cern.ch/garfield/files     for the files
  http://cern.ch/garfield/help      for help
!W
2 authors !D1 Heed has been written by Igor Smirnov, PNPI. !WHeed has been written by Igor Smirnov, PNPI. !D1 Magboltz is the work of Steve Biagi. !WMagboltz is the work of Steve Biagi. The TRIM interface has been contributed by James Butterworth. Most of Garfield has been written by Rob Veenhof (referred to as 'I' or 'me' in the documentation). The best way to contact me is !D1 by electronic mail at Rob.Veenhof@cern.ch. !Wby electronic mail. If you prefer more traditional means: !W
  Rob Veenhof            Rob Veenhof
  CERN / PH department   2, Rue du Reculet           
  CH-1211 Gen\ève 23      F-01630 St Genis-Pouilly
  Suisse                 France
  tel: + 41 22 7673222   tel: + 33 4 50421784
!W
A prompt response can not be guaranteed because maintaining this program is not part of my regular work, but I do my best. For technical questions and remarks about the control-C mechanism and other typical Vax features, please contact Carlo Mekenkamp directly (cmekenkamp@vx8000.nl). G.A. Erskine contributed key ideas but he should not be called in case of problems. Please contact me in case of questions about his parts (theta functions, polygon mappings). 2 origin The program was originally written (summer 1984) for the optimisation of the HELIOS drift chambers, which feature amongst others channeling, a non-linear and non-saturated gas (CO\2\-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: !Wul_start - cylindric geometries have been added; - a magnetic field can be taken into account; - interfaces with Magboltz and Heed have been added; - finite element field maps can be read. !Wul_end In 1984 the program had a length of 5000\ lines. By 2001, Garfield had grown to 127000\ lines (4.9\ Mb), while Magboltz and Heed count respectively 21800 and 19800\ lines (780\ kb and 507\ kb). 2 units The physical units used throughout for both input and output are the following: !Wtable_start !T+ + R . ------------------------------------------------------------------------ Dimension Input unit Internal unit ------------------------------------------------------------------------ angle degree radian B field user has the choice 100\ G charge electron charge 1.6 10\-19\ C current \μA 10\-18\ A energy eV [Garfield] or MeV [Heed] eV or MeV length centimetre cm potential Volt V pressure user has the choice Torr temperature user has the choice K time \μsec \μsec weight grams g line charge - V point charge V.cm V.cm ------------------------------------------------------------------------ !Wtable_end When the input unit is shown as "user has the choice", then the quantity can, on input, be followed by a unit of the users choice. If no unit is indicated, then internal units are assumed. To convert line charges into the more usual unit of C/cm, one should multiply the charge obtained from procedures such as "-> Call -> GET_WIRE_DATA" with 2\π\ε\0\, approximately 5.56\ 10\-13\\ C/V.cm. The wire charge shown in the table printed in response to the "-> &CELL -> OPTIONS -> CELL-PRINT" option and the "-> &OPTIMISE -> PRINT-CELL" command, includes this conversion factor. Similarly, to convert point charges to C, one should multiply the charge expressed in V.cm with 4\π\ε\0\. 2 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: !W
  http://cern.ch/garfield/files
!W
Executables at CERN can be found on AFS in the PaRC area, and also in the author's private area: !W
  /afs/cern.ch/user/r/rjd/Garfield/Files/garfield
!W
1 &MAIN Garfield input exists at 3 levels: !W
  Main \→ Cell section  \→ algebra sub-section
                         graphics sub-section
                         ...
         Gas section   \→ algebra sub-section
                         graphics sub-section
          ...
!W
The &MAIN command moves you back to the top level of program input, i.e. the level at which one enters the program. This is the normal environment to execute procedure "-> Call"s which use cell or gas data, e.g. in order to calculate drift-lines. &MAIN can also be used as final statement in jobs that run Magboltz to produce electron transport plots. &MAIN is in this context approximately equivalent to "-> &STOP". The cell and gas sections produce plots, write data sets and make their data available to the procedures when the section is left. Leaving the section can be done in 3\ ways: !Wul_start - by entering a new section; - by issuing a &MAIN command to return to the top level; - by issuing a &STOP command to stop program execution. !Wul_end A section is not left when an end-of-file condition is raised on input. Example: !W
  "-> Global" emin=100
  Global emax=10000
  "-> &MAGNETIC"
  "-> &MAGNETIC -> components" 0 0 0.4 T

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

  &MAIN
  Global n=100
  Global e=emin*(emax/emin)^(("-> algebra -> functions -> row"(n)-1)/(n-1))
  "-> Call" "-> Call -> transverse_diffusion"(e, 0, 0, 0, 0, 0.4, dt)
  Call "-> Call -> longitudinal_diffusion"(e, 0, 0, 0, 0, 0.4, dl)
  Call "-> Call -> plot_graph"(e,(dt^2+dl^2),`E [V/cm]`, ...
     `sqrt(σT2+σL2)`, ...
     `Diffusion`)
  Call "-> Call -> plot_end"
!W
Without the &MAIN statement, the "-> &GAS -> OPTIONS -> GAS-PLOT" option would have no effect, the "-> &GAS -> WRITE" statement would not be executed and the various procedure calls would be rejected. 1 &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: !W
  &CELL
!W
2 overview Cell sections come in 2 formats: !Wul_start - a full specification of the cell in the input - retrieval of a cell from a dataset !Wul_end Creating a new cell: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ CELL-IDENTIFIER Provides a short description to the cell CUT-SOLIDS Removes parts of solids 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 ------------------------------------------------------------------------ !Wtable_end Retrieving a cell from a dataset: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ GET Retrieves a compact cell description READ-FIELD-MAP Reads a binary field map ------------------------------------------------------------------------ !Wtable_end 2 methods 3 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: !Wtable_start !T+ + . ---------------------------------------------------------------------- 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 BEM Field calculated by neBEM MAP Finite element field maps ---------------------------------------------------------------------- !Wtable_end 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 periodicities, the distance between wires and planes etc. Versions of most potential functions exist which take advantage of vector hardware. The choice between scalar and vector versions is made a compilation time. Use "-> Call -> GET_CELL_DATA" to find out which potential function is in use. The cell type is also displayed when the "-> &CELL -> OPTIONS -> CELL-PRINT" option is active and in response to the "-> &OPTIMISE -> PRINT-CELL" command. Garfield has shape functions to deal with various element types such as straight triangles, curved triangles, straight tetrahedra, curved tetrahedra, hexahedra etc. Use "-> &CELL -> OPTIONS -> CELL-PRINT" as described above to find the shape functions used for the current chamber. neBEM has a range of Green's functions too: line elements, right-angled triangles and rectangles. Most models contain several of these elements at the same time. 3 coordinate_system Cells are described using one of the following 3 coordinate systems: !Wtable_start !T+S + . -------------------------------------------------------------------- Coordinate system Use -------------------------------------------------------------------- Cartesian Cells described in (x,y) coordinates, field maps Polar Cells described in (r,\φ) coordinates Tube Cells which contain a "-> &CELL -> TUBE" -------------------------------------------------------------------- !Wtable_end One can use the "-> Call -> GET_CELL_DATA" to find out which system is in use. 4 Cartesian In Garfield, the default coordinate system is a Cartesian system of (x,y,z) coordinates, all of which are expressed in units of cm. Such a system is used for chambers constructed from wires and planes unless one of the following conditions is met: !Wul_start - the chamber is declared to have a "-> &CELL -> PERIODICITY" in phi; - the chamber contains a "-> &CELL -> PLANE" at constant r or phi; - the chamber contains a "-> &CELL -> TUBE". !Wul_end 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, tetrahedral or rectangular coordinates, as appropriate. 4 Polar Chambers that have either a "-> &CELL -> PERIODICITY" in \φ or a "-> &CELL -> PLANE" at constant r or \φ, but no "-> &CELL -> TUBE" are described in polar coordinates: !Wul_start - r: distance from the origin, in cm; - \φ: angle with respect to the positive x-axis, in degrees; - z: distance from the (x,y) plane, in cm. !Wul_end Polar coordinates are internally dealt with by the conformal mapping: !W
  (x,y) = exp(\ρ,\φ)
  z     = \ζ
!W
thanks to which the potential functions and drift-line integration procedures for Cartesian coordinates can be used. Most of the commands accept polar coordinates for input and translate the the output to polar coordinates. Procedures as a rule don't do this. A set of procedures is therefore provided for these transformations: "-> Call -> CARTESIAN_TO_POLAR", "-> Call -> CARTESIAN_TO_INTERNAL", "-> Call -> INTERNAL_TO_CARTESIAN", "-> Call -> INTERNAL_TO_POLAR", "-> Call -> POLAR_TO_CARTESIAN" and "-> Call -> POLAR_TO_INTERNAL". 4 Tube Tube coordinates are used in chambers that contain a "-> &CELL -> TUBE", which can have "-> &CELL -> PERIODICITY" in \φ but in which there is no "-> &CELL -> PLANE". Tube coordinates are never used with field maps. 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: !W
      z - z0
  z = -----------
      1 - z0bar z
!W
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 mapped with a local Schwarz-Christoffel expansion. 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), in particular pp 108-110. 2 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 "-> introduction -> quotes": this will preserve the case and you may have blanks inside the string. The string can be retrieved by means of the "-> Call -> GET_CELL_DATA" procedure. The identification string is displayed in the plots using the "-> graphics -> REPRESENTATION -> item -> COMMENT" text representation. Format: !W
  CELL-IDENTIFIER string
!W
Example: !W
  CELL-ID "DC1 central cell"
!W
2 CUT-SOLIDS Removes the parts of the surface panels of solids that are located on one side of a plane, while keeping the remaining parts. After a cut operation, a solid will as a rule not be closed anymore. This does not pose a problem for neBEM field solutions provided that (mirror) periodicity conditions are applied. This command is executed when preparing neBEM panels, i.e. on leaving the cell section. Any error will therefore only be reported at this stage and not when the command is issued. For the same reason, these commands can be placed anywhere in the cell section, even before the solids are defined. When plotting the volumes, the outlines of solids do not reflect the cuts. Example: !W
  "-> &CELL"
  "-> Global" r=0.2
  "-> &CELL -> solids"
  "-> &CELL -> solids -> hole" "-> &CELL -> solids -> hole -> centre" 0 0 -0.1 ...
       "-> &CELL -> solids -> hole -> half-lengths" 2 2 0.1 ...
       "-> &CELL -> solids -> hole -> radius" {r} ...
       conductor-1 ...
       "-> &CELL -> solids -> hole -> label" a ...
       "-> &CELL -> solids -> hole -> voltage" -1
  hole centre 0 0  0.5 ...
       half-lengths 2 2 0.5 ...
       radius {r} ...
       epsilon 4 ...
       label a ...
       dielectric-1
  hole centre 0 0  1.1 ...
       half-lengths 2 2 0.1 ...
       radius {r} ...
       conductor-1 ...
       label a ...
       voltage 1
  hole centre 1 {sqrt(3)} -0.1 ...
       half-lengths 2 2 0.1 ...
       radius {r} ...
       conductor-1 ...
       label b ...
       voltage -1
  hole centre 1 {sqrt(3)}  0.5 ...
       half-lengths 2 2 0.5 ...
       radius {r} ...
       epsilon 4 ...
       label b ...
       dielectric-1
  hole centre 1 {sqrt(3)}  1.1 ...
       half-lengths 2 2 0.1 ...
       radius {r} ...
       conductor-1 ...
       label b ...
       voltage 1

  "-> &CELL -> nebem" "-> &CELL -> nebem -> maximum-elements"=3

  cut plane x>0 solids all
  cut plane y>0 solids all
  cut plane x<1 solids all
  cut plane y<{sqrt(3)} solids all
  cut plane y<{sqrt(3)/2} solids a
  cut plane y>{sqrt(3)/2} solids b

  "-> &FIELD"
  "-> &FIELD -> area" -0.5 -0.5 -0.5  1.5 2 1.5 view 2*x+7*y-3*z=0 "-> &FIELD -> area -> nebem"
  Call "-> Call -> plot_field_area"
  Call "-> Call -> plot_end"
!W
This example constructs the elementary cell of a GEM-like structure using 6 holes. The elementary cell contains 2 quarter-holes. The rest of the GEM is obtained by applying mirror symmetries in x and in y. Surface panels shown in red faced the inside (and were thus invisible) before the solids were cut. !W 2 DEFINE Defines a variable to be used in the listing of the "-> &CELL -> 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 "-> &CELL -> ROWS -> loop-variable" are evaluated automatically. Expressions in terms of global variables have to be enclosed by curly brackets to obtain "-> algebra -> variables -> substitution". Format: !W
  DEFINE "-> &CELL -> DEFINE -> variable" "-> &CELL -> DEFINE -> value"
!W
Example: !W
  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
!W
A simple resistor chain, the last line displays the value. You could in principle also enter the whole formula in the ROWS lines. !W
  "-> Global" resistor=5000
  define r_1 {resistor}
  define r_2 {resistor}
!W
The global variable RESISTOR is copied to the local variables R_1 and R_2. Note the use of curly brackets. 3 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 "-> algebra -> variables -> 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 "-> &CELL -> ROWS -> loop-variable". 3 value The value should be a valid "-> algebra"ic expression. Each variable may be defined in terms of previously defined variables and redefinition of variables is permitted at any time. 2 DIELECTRICUM !W
The current version of Garfield only takes dielectrics into account in a small number of configurations. It is preferable to use the neBEM interface or a finite elements program to generate a field map and to read such a map in with the "-> &CELL -> FIELD-MAP" instruction. !W
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. Wire may be located inside dielectric media, but the media must be inside the equipotential planes, if there are any in your cell. Dielectrics slow the program down significantly. Format: !W
  DIELECTRICUM {X-RANGE|Y-RANGE} min max EPSILON \ε
!W
Example: !W
  DIELECTRICUM X -10 10 EPS 5
!W
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 min_max The range along the specified coordinate axis the slab should cover. No default provided. 3 \ε The dielectric constant of the material relative to vacuum. The constant has to be larger than 0. There is no default for this parameter. 2 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 "-> &CELL -> FIELD-MAP -> FILES -> format" generated by ANSYS, Maxwell Parameter Extractor 2D and 3D, Maxwell Field Simulator 2D and 3D as well as by Tosca can be read. Interfaces for files produced by other programs can be added on request (please contact the author). When you read a field map in the cell section, any wire, plane, periodicity, dielectric medium and magnetic field that you entered sofar is deleted. Also field map components read with earlier FIELD-MAP commands are deleted. The optimisation section has a "-> &OPTIMISE -> FIELD-MAP" command too. The field maps entered in the cell section serve as main field, i.e. this field map replaces the field generated by wires and planes. The field maps entered in the optimisation section are used e.g. when a finite element weighting field is needed in conjunction with a main field computed from wires and planes (see the "-> &OPTIMISE -> FIELD-MAP -> weighting_field" example), or when space charge computed with a finite element program is superimposed on a main field calculated for wires and planes. The two field maps share (for the moment) the same storage and can therefore not be used at the same time. Reading large field maps is time consuming. To save time, you consider saving your field maps in binary format with "-> &CELL -> SAVE-FIELD-MAP". Binary field maps are retrieved with "-> &CELL -> READ-FIELD-MAP". Binary field maps are much smaller and much faster to read in, but they are not portable between computer systems. The FIELD-MAP command can read magnetic fields computed by finite element programs. For the moment, there is no experience with such fields. Format: !W
  FIELD-MAP ["-> &CELL -> FIELD-MAP -> FILES" ["-> &CELL -> FIELD-MAP -> FILES -> contents"_1] "-> &CELL -> FIELD-MAP -> FILES -> file"_1 [LABEL "-> &CELL -> FIELD-MAP -> FILES -> label"_1] ...
                   [contents_2] file_2 [LABEL label_2] ...
                   ...
                   [contents_n] file_n [LABEL label_n] ...
                   ["-> &CELL -> FIELD-MAP -> FILES -> format"] ] ...
            ["-> &CELL -> FIELD-MAP -> DRIFT-MEDIUM" {SMALLEST-EPSILON | ...
                           SECOND-SMALLEST-EPSILON | ...
                           n | ...
                           SECOND-LARGEST-EPSILON | ...
                           LARGEST-EPSILON | ...
                           \ε}] ...
            ["-> &CELL -> FIELD-MAP -> NOT-X-PERIODIC" | "-> &CELL -> FIELD-MAP -> X-PERIODIC" | "-> &CELL -> FIELD-MAP -> X-MIRROR-PERIODIC" | "-> &CELL -> FIELD-MAP -> X-AXIALLY-PERIODIC"] ...
            ["-> &CELL -> FIELD-MAP -> NOT-Y-PERIODIC" | "-> &CELL -> FIELD-MAP -> Y-PERIODIC" | "-> &CELL -> FIELD-MAP -> Y-MIRROR-PERIODIC" | "-> &CELL -> FIELD-MAP -> Y-AXIALLY-PERIODIC"] ...
            ["-> &CELL -> FIELD-MAP -> NOT-Z-PERIODIC" | "-> &CELL -> FIELD-MAP -> Z-PERIODIC" | "-> &CELL -> FIELD-MAP -> Z-MIRROR-PERIODIC" | "-> &CELL -> FIELD-MAP -> Z-AXIALLY-PERIODIC"] ...
            ["-> &CELL -> FIELD-MAP -> X-ROTATIONALLY-SYMMETRIC" | "-> &CELL -> FIELD-MAP -> Y-ROTATIONALLY-SYMMETRIC" | "-> &CELL -> FIELD-MAP -> Z-ROTATIONALLY-SYMMETRIC"] ...
            ["-> &CELL -> FIELD-MAP -> LINEAR" | "-> &CELL -> FIELD-MAP -> QUADRATIC" | "-> &CELL -> FIELD-MAP -> CUBIC"] ...
            ["-> &CELL -> FIELD-MAP -> INTERPOLATE-ELECTRIC-FIELD" | "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD"] ...
            ["-> &CELL -> FIELD-MAP -> DELETE-BACKGROUND" | KEEP-BACKGROUND] ...
            ["-> &CELL -> FIELD-MAP -> UNIT" {MICROMETRE | MILLIMETRE | CENTIMETRE | METRE}] ...
            ["-> &CELL -> FIELD-MAP -> Z-RANGE" zmin zmax] ...
            ["-> &CELL -> FIELD-MAP -> OFFSET" xoff yoff zoff] ...
            ["-> &CELL -> FIELD-MAP -> PLOT-MAP" | NOPLOT-MAP] ...
            [NOHISTOGRAM-MAP | "-> &CELL -> FIELD-MAP -> HISTOGRAM-MAP"] ...
            ["-> &CELL -> FIELD-MAP -> RESET"]
!W
Example: !W
  &CELL
  field-map files "e_field.arg" "potential.arg" "epsilon.arg" ...
            drift-medium second-smallest ...
            x-periodic
!W
(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 FILES The set of files to be read in. The files can contain the mesh or maps of: !Wul_start - the potential, - the electric E-field, - the electric D-field, - one or more weighting fields, - the magnetic field, - the dielectric constant. !Wul_end Notes: !Wol_start 1. All maps, weighting fields included, must share the same grid. 2. The weighting field of an electrode is the electric field that results from setting the potential of that electrode to 1 and all others to 0. (Strictly speaking, the potential should be 1, and not 1\ V.) 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. 4. Should you, under duress, have to use Windows to prepare the field maps, then take care to remove spurious end-of-line sequences, such as control-M, from the field maps. !Wol_end 4 contents One may specify the contents of the file before the name. This is mandatory in the following cases: !Wul_start - field maps of which the "-> &CELL -> FIELD-MAP -> FILES -> format" can not be identified automatically, such as "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-plane-121"; "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123"; "-> &CELL -> FIELD-MAP -> FILES -> format -> Tosca", "-> &CELL -> FIELD-MAP -> FILES -> format -> Tosca-118", "-> &CELL -> FIELD-MAP -> FILES -> format -> Maxwell-2D-SV", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2D-LINEAR", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2D-QUADRATIC" (formerly called FEMLAB-2D), "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-LINEAR", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-QUADRATIC" (formerly called FEMLAB-3D), "-> &CELL -> FIELD-MAP -> FILES -> format -> QuickField" - files that contain a weighting field. !Wul_end 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: !Wtable_start !T+SP + + . -------------------------------------------------------------------------- Name Synonyms Used to compute -------------------------------------------------------------------------- B-FIELD MAGNETIC-FIELD Drift-lines ELECTRIC-FIELD - Drift-lines, various other plots D-FIELD - \ε by comparing E and D MATERIAL D-FIELD Drift-line termination MESH - Mesh structure of Maxwell Field Simulator MODEL - Problem domain in Maxwell 2D SV BACKGROUND - Model vs background, Maxwell 11 POTENTIAL VOLTAGE Contour maps WEIGHTING-FIELD - Induced signals -------------------------------------------------------------------------- !Wtable_end 5 B-FIELD 5 ELECTRIC-FIELD Some finite element programs output maps of the electric field, most do not. One reason is that the electric field is discontinuous across element boundaries. As a result, a node will typically have as many different electric field values associated with it, as there are elements of which the node is part. Potentials in contrast are unique. Another reason is that the shape function method enables one to compute the electric field from the potential without need to take numerical derivatives. One does need the Jacobian of the coordinate transformation, but this is anyhow needed to compute the local isoparametric coordinates. In other words, there is no significant gain in CPU time, and a major saving in memory, if one computes the electric field as needed, using the potentials. The first finite element interfaces developed for Garfield were for programs that did output the electric field maps - and Garfield still allocates memory to store the electric field maps. All interfaces developed later arrange for the electric field to be computed from the potential map and it is expected that the stored electric field map will disappear in the foreseeable future. See also the "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" and "-> &CELL -> FIELD-MAP -> INTERPOLATE-ELECTRIC-FIELD" options. 5 D-FIELD 5 MATERIAL 5 MESH 5 MODEL 5 BACKGROUND 5 POTENTIAL The potential, even though not used for the simulations of physics processes, plays nevertheless a key role when the field calculations are performed using the finite element method: the primary quantity computed by these programs is the potential, and the electric field is computed (by Garfield, in many cases) from the potential. 5 WEIGHTING-FIELD Weighting fields form the basis of signal calculations. Induced currents are proportional to the charge Q of the moving particle as well as its velocity v. The current not only depends on the magnitude of the velocity but also on the direction of motion: a charged particle moving parallel with the plates of a capacitor doesn't induce (net) current in the capacitor plates while a charged particle moving perpendicular to the plates will induce a current. Since the current is a scalar and the velocity a vector, an intuitively plausible ansatz for the current reads: !W
  I = factor Q Ew.v
!W
where Ew is a vectorial quantity called "weighting field". The formula can be derived using Green reciprocity and the factor turns out to be equal to -1. Such a calculation also shows that the weighting field Ew is obtained by setting the potential of all conductors to 0, except for the conductor (or set of conductors) that is read out. The potential of these conductors is to be set to 1. Weighting fields resemble ordinary electric fields, and finite element programs do not distinguish them from electric fields. There are differences, though. For instance, as can be seen from the above formula, the unit of the weighting field is 1/cm, not V/cm. Garfield stores only one mesh at the time and uses this mesh both for the ordinary field and for the weighting field. Care needs to be taken therefore that no mesh refinements occur between solving for the 2 types of field. Finite element programs such as ANSYS output the weighting potential instead of the weighting field - Garfield computes the gradient internally. 4 file The name of the dataset that contains the field map or the mesh. These files are usually written by other programs than Garfield, and they therefore do not follow internally the Garfield format conventions. For notes on the way dataset names should be supplied to Garfield, see the guidelines for Garfield "-> dataset -> structure -> file"s. For recipes for making these files, refer to the file "-> &CELL -> FIELD-MAP -> FILES -> format" descriptions. 4 label Gives a name to a weighting field map. No label should be assigned to other fields than the weighting fields. The label is a single upper case alphabetic character which serves two purposes: !Wol_start 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 "-> &CELL -> 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, e.g. because no solids have been entered, all signals on the weighting field map are classified as cross induced. Such signals are only computed if the "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED" option is active. 2. The label identifies the weighting field to the "-> &SIGNAL -> SELECT" statement, a prerequisite for the computation of signals in the electrodes for which the weighting field has been computed. !Wol_end As for all finite element field maps, weighting field maps can be entered both in the cell section and in the optimisation section. When the main field is computed using a finite element program, then the weighting fields are entered, together with the main field, in the cell section. Entry of a weighting field in the optimisation section is used for "-> &OPTIMISE -> FIELD-MAP -> weighting_field" example when the main field can be calculated nearly exactly from wires and planes, while the shape of the read-out electrodes (typically pads) is such that the weighting field is more easily calculated using finite elements. [By default, the label "S" is assigned to weighting field maps, which makes these maps are part of the initial, default, selection.] 4 format Specifies the program that has been used to generate the field maps. Currently, the following formats are accepted: !Wul_start - "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-plane-121"; - "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123"; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Tosca", from Vector Fields; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Tosca-118", - "-> &CELL -> FIELD-MAP -> FILES -> format -> QuickField"; - "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2D-LINEAR"; - "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2D-QUADRATIC", formerly called FEMlab-2D; - "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-LINEAR"; - "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-QUADRATIC", formerly called FEMlab-3D; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Parameter-Extractor-2D", from Ansoft; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Parameter-Extractor-3D", from Ansoft; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Field-Simulator-3D", from Ansoft; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Maxwell-2D-SV", from Ansoft; - "-> &CELL -> FIELD-MAP -> FILES -> format -> Maxwell-11", from Ansoft. !Wul_end The layout of the field maps for the various Maxwell versions is so similar that Garfield can only rarely tell which version has been used. As of version\ 11, the situation is even worse in that the layout of version\ 9 and version\ 11 files is identical, but the node numbering sequence is different. It is therefore advisable to systematically specify the format explicitly. 5 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. The "-> &CELL -> FIELD-MAP -> FILES -> contents" needs to be specified only for weighting fields. To generate your field maps with Maxwell Parameter Extractor 2D, you may wish to follow this recipe: !Wol_start 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: !Wul_start - In "Electrostatic" mode: click again on "calc", select again "plane", do a "clear" if needed. Click on "E_vector", then on "vec_cons", fill in 1\ 0\ 0 as vector, click on "execute", click on "Materials", click on "epsilon", ensure that multiplication is set to "yes" and "execute", then click on "scalar_x" and do an ASCII "write" of the result. Choose a file name different from those used in steps\ 2 and 3. This procedure leads to a file that contains the dielectric constant. - If you model you chamber in "DC conduction mode", then apply the same recipe with "epsilon" replaced by "sigma". !Wul_end 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. !Wol_end These steps should lead to a set files with names that end on .arg and that are located in the es.pjt sub-directory of your project. Be sure to create the E, V, \ε or \σ and weighting field maps with identical meshes and the E, V and \εor \σ 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. Maxwell documentation at CERN can be found in http://wwwinfo.cern.ch/ce/ae/Maxwell/documentation.html !D1 (Instructions from Pawel Majewski) !W(Instructions from Pawel Majewski) 5 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. The "-> &CELL -> FIELD-MAP -> FILES -> contents" needs to be specified only for weighting fields. To generate your field maps with Maxwell\ 2D Field Simulator, you may like to follow the following recipe: !Wol_start 1. Go through the various steps until "Solve". Then enter "Post Process" for the "nominal problem" where you click on "calc", select "Plane" and, if the upper area is not empty click on "clear". 2. 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 automatically 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: !Wul_start - Repeat step\ 2 with "D_Vector" instead of "voltage", choosing a file name different from those in steps 2 and 3. This creates a file with a field map of D. The dielectric constant is computed by Comparing D and E. - Do a "clear", then click on "E_Vector", then on "vec_cons", fill in 1\ 0\ 0 as vector, click on "Execute", click on "Materials", click on "epsilon", ensure that multiplication is set to "Yes" and "Execute", then click on "scalar_x" and do an ASCII "write" of the result. Choose a file name different from those used in steps\ 2 and 3. This procedure creates to a file that contains the dielectric constant. - If you model you chamber in "DC conduction" mode, then apply the above recipe with "epsilon" replaced by "sigma". !Wul_end 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. !Wol_end 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, D, \ε or \σ and weighting field maps with identical meshes and in addition the E, V and D 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://wwwinfo.cern.ch/ce/ae/Maxwell/Maxwell.html 5 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 and the "-> &CELL -> FIELD-MAP -> FILES -> contents" needs to be indicated only for weighting fields. When generating your field maps with this program, you may wish to follow this recipe: !Wol_start 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" where you click on "calc", select "space" and, if the upper area is not empty click on "clear". 2. 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 automatically 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. !Wol_end 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 sub-directory 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://wwwinfo.cern.ch/ce/ae/Maxwell/Maxwell.html 5 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. The "-> &CELL -> FIELD-MAP -> FILES -> contents" needs to be specified only for the mesh files and the weighting field. Beware that files produced with Maxwell Version\ 11 can be read with the interface for earlier versions, and vice-versa, but the results will be incorrect. Be sure therefore to specify the correct Maxwell version on the FIELD-MAP command line. When you use this program to create your field maps, you have to provide the following to Garfield: !Wol_start 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" sub-directory of the project directory). When using the "-> &CELL -> FIELD-MAP -> DELETE-BACKGROUND" option, the project .shd file is needed in addition. The files have names like "fileset2", "fileset1", "current", "efs3d", "previous" and "initial". !Wul_start - If you do not specify a mesh file explicitly, then Garfield will look in the directory of the first field map for mesh files with the above names, starting from "fileset2". - To select a mesh manually, you provide the name of the .pnt, .hyd or .shd file (complete file name) and either place this name first in the list of files to be read, or identify it explicitly as containing a mesh by prefixing the MESH keyword. !Wul_end 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. !Wol_end Be sure to create the E, V, D and weighting field maps with identical meshes and the E, V and D maps in addition with identical boundary conditions. Information about using Maxwell at CERN can be found in http://wwwinfo.cern.ch/ce/ae/Maxwell/Maxwell.html 5 MAXWELL-2D-SV Specifies that the field maps have been produced with Maxwell Student Version or 2D\ version\ 9. This program only solves 2D problems, either in x-y or in r-z coordinates. The recipe to generate the field map files doesn't depend on the coordinate system. After having worked your way through the various steps from model definition till problem solving, click on "Post\ Process\ ..." and enter "Data/Calculator". Then: !Wol_start 1. Click on "Qty" 2. Select "phi" to create a map of the potential 3. Click on "Write ..." 4. Enter a name for the file (the extension *.reg will be appended automatically to the file name.) !Wol_end For the maps of the electric field and the dielectric constant, repeat the above procedure selecting "E" and "D" instead of "phi" in step 2 and entering an appropriate file name in step 4. Alternatively, the electric field can be derived from the potential by selecting the "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" option. Several users have reported problems with the electric field maps as exported by Maxwell and this approach can therefore be recommended. When using Maxwell SV, you have to feed the following files to Garfield: !Wul_start - The mesh files preceded by the "-> &CELL -> FIELD-MAP -> FILES -> contents" indication MESH. Maxwell SV, contrary to earlier 2D versions of Maxwell, does not insert mesh information in the field maps. Garfield extracts the mesh structure from 2 files: a list of triangles (which has an extension of .tri) that contains pointers to a file with a list of mesh coordinates (extension .pts). Garfield will automatically read these files if they are located in the same directory as the field maps and have a file name of "fileset1" or of "fileset2". You may move these 2 files elsewhere and change their names, provided that they are given the same file name, that the extensions are unchanged and that the 2 files are placed in the same directory. You then also have to inform Garfield of the directory and file name by specifying one (and only one) of these files - the extension doesn't matter since Garfield fills it in itself. - The model file preceded by the "-> &CELL -> FIELD-MAP -> FILES -> contents" indication MODEL. The extension of this file is .sm2 and the file name is usually the same as the project name. Maxwell SV, like some other Ansoft programs, solves the problem in normalised mesh coordinates and the mesh files do not contain information regarding the problem domain. Garfield extracts the dimensions of the problem domain from the model file. The problem domain is set to the square region (-1,-1) to (1,1) in case the model file isn't read. - The field maps, optionally preceded by a keyword to indicate the "-> &CELL -> FIELD-MAP -> FILES -> contents". - You may in addition supply weighting fields. Weighting fields are computed as electric fields but the potential of all conductors should be set to 0 except the read-out conductor which is set to 1. Be sure to create the E, V, D and weighting field maps with identical meshes. This is achieved by first solving for E, V and D, then disabling mesh refinements when solving for the weighting fields. The E, V and D maps should in addition have identical boundary conditions. !Wul_end An axis of rotational symmetry, if any, should be detected automatically and result in the "-> &CELL -> FIELD-MAP -> Z-ROTATIONALLY-SYMMETRIC" option being switched on. (Procedure from Pawel Majewski.) 5 TOSCA To generate your field maps with Tosca on a Unix system, you have to: !Wol_start 1. use OPERA version\ 7.0. 2. !Wul_start - create the directory $VFDIR/opera/3d/util - copy in this directory the Makefile and the program util.f which can be found in http://consult.cern.ch/writeup/garfield/examples/tosca - run in the same directory the command "$VFDIR/install/makeprog $VFDIR" !Wul_end 3. Generate the geometrical mesh with the 3d Opera preprocessor. 4. Click on "MESH" and then choose the "quadrilaters" option. 5. Click again on "MESH" and choose the "Volume\ mesh\ ...\ Mesh\ *" option. 6. Click on "FILE" and choose the "write node table" option in order to create the "username.table" file that contains the mesh node coordinates. 7. Generate, clicking again on "FILE", the usual username.OP3 file ready to be analysed by TOSCA. 8. Run the Fortran program "util" with the command: $VFDIR/opera/3d/util > "username1.table" and, after pushing the "return" button, 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. 9. Run TOSCA. 0. Run the 3d\ Opera post-processor. Load the TOSCA result. Click on "FIELDS" and choose the "table of field points" sub-menu. In this sub-menu: !Wol_start a. Select "input from file" and give "username.table" (see item\ 6 above) as input. b. Choose an "username2.table" as output according to your taste c. Click on "output components options" and define: !Wul_start - 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 !Wul_end d. Click the "process table" option that will describe, for each mesh node, the value of the electric field and potential. !Wol_end !Wol_end 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 "-> &CELL -> FIELD-MAP -> FILES -> 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. It is advisable to use the "-> &CELL -> FIELD-MAP -> INTERPOLATE-ELECTRIC-FIELD" option when using Tosca field maps. !D2 (Recipe from Guido Maria Urciuoli, INFN Gruppo Collegata Sanita', Viale Regina Elena 299, 00161 Roma, Italia.) !W(Recipe from Guido Maria Urciuoli, !WINFN Gruppo Collegata Sanitá, Viale Regina Elena 299, 00161 Roma, Italia.) 5 TOSCA-118 Indicates that the field map has been generated with Tosca using curved quadratic tetrahedra. The interface has been tested with files created using Tosca version 11.006. The Tosca file, called a "simulation database" in Tosca-speak, should contain at least the following Tosca "datasets": !Wul_start - 164: units - 2412: mesh structure - 2411: node location - 2414: potential solution !Wul_end A recipe to create this file follows. After the model has been created in the Modeller, create the simulation database with !Wul_start - 'element type' = quadratic and - 'surface element type' = curved: !Wul_end To achieve this, enter at the console: !W
  SOLVERS PROGRAM=&VF_ANALYSISTYPE& -SOLVENOW OPTION=NEW
          ELEMENT=QUADRATIC SURFACE=CURVED FILE='YourFileName.op3';
!W
or follow the GUI path: !W
  Model \→ Create Analysis Database...
!W
In the post-processor export the results to an I-DEAS Universal File, where it important is to set BASIS=ELEMENT, i.e. write values at every node of every element: As a console command: !W
  IDEAS FILE='YourFileName.unv' MODE=CREATE TYPE=REAL
        BASIS=ELEMENT FIELD=SCALAR COMP=V;
!W
or using the GUI: !W
  Tables \→ SDRC I-DEAS Unv File...
!W
(Recipe provided by Konstantin Klementiev .) 5 COMSOL-2D-LINEAR Indicates that the field map has been prepared by the COMSOL 2D programme using 1st order triangular elements. These elements have only 3 nodes, the potential is linear within each element and the local gradient is constant. Although such field maps can be read, their use is not recommended. Use instead "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2D-QUADRATIC". 5 COMSOL-2D-QUADRATIC Indicates that the field map has been prepared by the Comsol 2D programme using 2nd order triangular elements. For the recipe to write such field maps, please refer to "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-QUADRATIC". Garfield doesn't recognise this format automatically, be sure therefore to specify that your field map is in COMSOL-2D-QUADRATIC format. You may specify a distance "-> &CELL -> FIELD-MAP -> unit" for such field maps, centimetres are assumed if no unit is given. Example: !W
  "-> &CELL"
  "-> &CELL -> field-map" "-> &CELL -> FIELD-MAP -> files" "-> &CELL -> FIELD-MAP -> FILES -> contents -> potential" "COMSOLFIELD2D.txt" ...
                  "-> &CELL -> FIELD-MAP -> FILES -> contents -> weighting-field" "COMSOLFIELD2DElectrode1.txt" "-> &CELL -> FIELD-MAP -> FILES -> label" s ...
          comsol-2d

  "-> &FIELD"
  "-> &FIELD -> plot-field" "-> &FIELD -> PLOT-FIELD -> contour" v

  "-> &SIGNAL"
  "-> &SIGNAL -> select" s
  "-> &SIGNAL -> plot-field" "-> &SIGNAL -> plot-field -> vector"
!W
Two potential maps are read, the first contains the potential, the second the weighting potential for one of the electrodes. The latter is associated with label S which is later used in the signal section to plot the weighting field map. 5 COMSOL-3D-LINEAR Indicates that the field map has been prepared by the COMSOL 3D programme using 1st order tetrahedral elements. These elements have only 4 nodes, the potential is linear within each element and the local gradient is constant. Although such field maps can be read, their use is not recommended. Use instead "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3D-QUADRATIC". 5 COMSOL-3D-QUADRATIC Indicates that the field map has been prepared by the Comsol 3D programme. Garfield doesn't recognise this format automatically, be sure therefore to specify that your field map is in COMSOL-3D format. You may specify a distance "-> &CELL -> FIELD-MAP -> unit" for such field maps, centimetres are assumed if no unit is given. First, solve your problem in COMSOL. Take care to select 2nd order Lagrange elements. Then export the field map as follows: !Wol_start 1. Go to menu File \→ Export \→ Post-Processing Data 2. Set path/filename to export, e.g. "exported.txt" 3. Choose file format "Nodes, elements, data" 4. Check that under the "Subdomain" tab "Electric Potential" is selected as Expression to export 5. Click "OK" to write the file !Wol_end To import the file in Garfield: !Wol_start 1. Go to cell section ("-> &CELL"). 2. Import the exported file using the "-> &CELL -> FIELD-MAP" command, this may take quite some time depending on the size of the map. 3. Garfield does not recognise this format automatically, hence be sure to specify that your field map is in COMSOL-3D format. 4. If you get a warning stating that the number of tetrahedrons exceeds the compilation limit, then recompile Garfield with a larger value for MXMAP. Alternatively, check the quality of the mesh - large field maps frequently result from poorly refined field maps. These not only slow down all calculations performed with them, they also are of poor numeric quality. You may also wish to consider using virtual volumes surrounding tiny electrodes. 5. To save time next time you need the field map, you may wish to write a binary copy using "-> &CELL -> SAVE-FIELD-MAP". !Wol_end Example: !W
  "-> &CELL"
  field-map files "exported.txt" comsol-3d
  "-> &CELL -> save-field-map" "exported.bin"
!W
(Recipe written by Jeremy Janney and Sven Lotze .) 5 ANSYS-PLANE-121 ANSYS uses the 8-node curved quadrilateral, sometimes known as "serendipity" element, for 2-dimensional electrostatic problems. ANSYS will occasionally generate degenerate quadrilaterals, which are curved quadratic triangles. The recipe assumes that the command format is used. Most of the commands cited can of course also be run from the GUI. !Wol_start 0. Clear earlier calculations and enter the pre-processor: !W
     FINISH  
     /CLEAR,START
     /PREP7  
!W
1. If using the GUI, enter the preferences and ensure that the only discipline selected within the "Electromagnetic" group is "Electric". The equivalent commands are: !W
     KEYW,PR_ELMAG,1
     KEYW,MAGELC,1   
!W
Disable the p-method solution options. This option leads to elements of higher polynomial order, which are a priori preferred, but Garfield does not yet have shape functions for these. !W
     /PMETH,OFF,1
!W
2. Select the quadrilateral as element: !W
     ET,1,PLANE121   
!W
In case your chamber has rotational symmetry around an axis, a non-default element behaviour needs to be selected: !W
     ET,1,PLANE121   ! Select plane quadrilaterals
     KEYOPT,1,3,1    ! Declare the element to be axisymmetric
!W
In ANSYS, the y-axis acts as axis of rotational symmetry and no part of the model should be located in x\ \<\ 0. When reading the field map with Garfield, you have to declare the symmetry again using "-> &CELL -> FIELD-MAP -> X-ROTATIONALLY-SYMMETRIC", "-> &CELL -> FIELD-MAP -> Y-ROTATIONALLY-SYMMETRIC" or "-> &CELL -> FIELD-MAP -> Z-ROTATIONALLY-SYMMETRIC". 3. When defining material properties, be sure that every material has its permittivity set. Choose material numbers starting from 1 and leave no holes in the numbering. Set the permittivity of conductors to a very high value. Set the resistivity of perfect conductors to 0 so as to make them eligible for removal as background (see the "-> &CELL -> FIELD-MAP -> DELETE-BACKGROUND" option). Try to avoid temperature-dependent properties as these can not be used by Garfield to identify materials. If you need to use them, then do not write out the MPLIST file (see below). For instance, to define a perfect conductor (material\ 1) and a dielectricum (material\ 2): !W
     MP, PERX, 1, 1e10 ! Metal
     MP, RSVX, 1, 0.0
     MP, PERX, 2, 4.5  ! Bulk dielectric constant
!W
4. Create the model. See any of the numerous ANSYS tutorials for advice. Pay particular particular attention to gluing adjacent areas where necessary (AGLUE command). For instance, to create a conducting strip on the wall of a block of dielectric material: !W
     ! Define some dimensions, in microns
     halfpitch = 50
     thickbulk = 200
     halfstrip = 20
     thickstrip = 5

     BLC4, 0, 0, halfpitch, thickbulk   ! Area 1: dielectricum
     BLC4, 0, 0, halfstrip, thickstrip  ! Area 2: conductor
     ASBA, 1, 2, , , KEEP               ! Area 1 becomes area 3

     AGLUE, ALL                         ! Glue everything
!W
5. Assign material properties with the AATT command: !W
     ASEL, S, , , 3             ! Select the dielectricum
     AATT, 2                    ! Properties of material 2
     ASEL, S, , , 2             ! Select the conductor
     AATT, 1                    ! Properties of material 1
!W
6. Set boundary conditions: !W
     ASEL, S, , , 2             ! Select the metal
     LSLA, S                    ! Select all its border lines
     DL, ALL, 2, VOLT, 1000     ! Set the borders to 1000 V

     ASEL, S, , , 3             ! Select the dielectricum
     LSLA, S                    ! Select all its border lines
     LSEL, R, LOC, Y, thickbulk ! Sub-select lines at y=thickbulk
     DL, ALL, 3, VOLT, 0        ! Set this line to 0 V

     ASEL, S, , , 3
     LSLA, S
     LSEL, R, LOC, X, 0         ! Select the lines at x=0
     DL, ALL, 3, SYMM           ! Impose a symmetry condition
     ASEL, S, , , 3
     LSLA, S
     LSEL, R, LOC, X, halfpitch ! Idem for y=halfpitch
     DL, ALL, 3, SYMM
!W
7. Mesh the problem. This can for instance be done using free meshing: !W
     LSEL,ALL
     ASEL, ALL
     MSHKEY,0
     SMRT, 3
     AMESH, 2,3
!W
It is not always necessary to mesh the metal parts of the device. Then solve the problem: !W
     /SOLU
     SOLVE   
     FINISH  
!W
Optionally visualise the solution: !W
     /POST1  
     /EFACET,1   
     PLNSOL, VOLT,, 0
!W
8. Write the solution to files. The potentials at the nodes are written to a file with the PRNSOL command. In the example below, the file name is chosen to be "PRNSOL.lis" but feel free to use another name. It is the name of this "-> &CELL -> FIELD-MAP -> FILES -> file" which must follow the "-> &CELL -> FIELD-MAP -> FILES" keyword. !W
     /OUTPUT, PRNSOL, lis
     PRNSOL
     /OUTPUT
!W
There is no need to write the electric field to a file since the "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" option is implied when using ANSYS. The PRNSOL file contains the potentials at the nodes. When interpolating between nodes, Garfield needs to know where each of these nodes is located in space. This information is contained in the output of the NLIST command, which should be written to a file called "NLIST.lis". Note the COORD option - without this option, the file would contain additional information which is not used in Garfield, at the price of reduced precision in the node coordinates. Garfield can read files in either format - but the COORD option is recommended. !W
     /OUTPUT, NLIST, lis
     NLIST,,,,COORD
     /OUTPUT
!W
Garfield also needs to know how the nodes are tied into elements. This structure is shown by the ELIST command, of which the output has to be written to a file called "ELIST.lis": !W
     /OUTPUT, ELIST, lis
     ELIST
     /OUTPUT
!W
Optionally, you may transmit the dielectric constants (permittivities) and the electric resistivities to Garfield. Only write this file if your material properties do not have a temperature dependence. The commands for writing the "MPLIST.lis" file are as follows: !W
     /OUTPUT, MPLIST, lis
     MPLIST
     /OUTPUT
!W
If you produce the field maps on operating systems like Windows, control-M will be appended to each line. These need to be removed before the field maps can be read with Garfield. 9. Make Garfield read the field maps. You only need to specify the potential map. The remaining files, ELIST.lis, NLIST.lis and MPLIST.lis are searched for in the same directory. An example follows. Since ANSYS allows the user to use any consistent system of units, the real size of the device can not be found in the field map files. The user therefore has to specify the distance "-> &CELL -> FIELD-MAP -> UNIT". !W
     "-> &CELL"
     field-map files "../scratch0/PRNSOL.lis" ansys-plane-121 ...
        x-mirror-periodic unit micron

     "-> &FIELD"
     "-> &FIELD -> area" -0.0100 0 0.0100 0.0200
     "-> &FIELD -> plot-field" cont v
!W
!Wol_end In order to compute signals, Garfield needs weighting fields. Refer to the "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123" recipe. 5 ANSYS-SOLID-123 ANSYS offers two element types for 3-dimensional electrostatic problems: the quadratic curved tetrahedron and the brick. The recipe below uses the former, known as "solid\ 123" in ANSYS. Garfield currently doesn't have an interface for the other element, "solid\ 122". The recipe assumes that the command format is used. Most of the commands cited can of course also be run from the GUI. !Wol_start 0. Clear earlier calculations and enter the pre-processor: !W
     FINISH  
     /CLEAR,START
     /PREP7  
!W
1. If using the GUI, enter the preferences and ensure that the only discipline selected is "Electric" within "Electromagnetic": !W
     KEYW,PR_ELMAG,1
     KEYW,MAGELC,1   
!W
Disable the p-method solution options. This option leads to elements of higher polynomial order, which are a priori preferred, but Garfield does not yet have shape functions for these. !W
     /PMETH,OFF,1
!W
2. Select the 2nd\ order tetrahedron as element: !W
     ET,1,SOLID123
!W
3. When defining material properties, be sure that every material has its permittivity set. Choose material numbers starting from 1 and leave no holes in the numbering. Set the permittivity of conductors to a very high value. Set the resistivity of perfect conductors to 0 so as to make them eligible for removal as background (see the "-> &CELL -> FIELD-MAP -> DELETE-BACKGROUND" option). Try to avoid temperature-dependent properties as these can not be used by Garfield to identify materials. If you need to use them, then do not write out the MPLIST file (see below). For instance, to define a perfect conductor (material\ 1), a gas (material 2) and a dielectricum (material\ 3): !W
     MP,PERX,1,1e10  ! Metal
     MP,RSVX,1,0     !
     MP,PERX,2,1     ! Gas
     MP,PERX,3,4.5   ! Dielectricum
!W
4. Create the model. See any of the numerous ANSYS tutorials for advice. Pay particular particular attention to gluing adjacent volumes where necessary (VGLUE command). 5. Assign material properties with the VATT command. 6. Set boundary conditions. To set for instance the voltage on all surface areas of volume\ 2 (assumed to be a conductor) to 100\ V: !W
     VSEL, S, VOLU, , 2 ! Select volume 2
     ASLV, S            ! Select all areas belonging to the selected volumes
     DA, ALL, VOLT, 100 ! Set a voltage boundary on all selected areas
!W
Similarly, a symmetry boundary on all selected areas can be set with the command: !W
     DA, ALL, SYMM
!W
7. Mesh the problem. This can be done in numerous manners. For instance, to have a fine mesh, using free meshing, in volumes 1, 2, 3 and 15: !W
     SMRT, 2
     MSHKEY,0
     VMESH, 1, 3
     VMESH, 15
!W
It is not always necessary to mesh the metal parts of the device. Then solve the problem: !W
     /SOLU
     SOLVE   
!W
Optionally visualise the solution: !W
     /POST1  
     /EFACET,1   
     PLNSOL, VOLT,, 0
!W
8. Write the solution to files. The potentials at the nodes are written to a file with the PRNSOL command. In the example below, the file name is chosen to be "PRNSOL.lis" but feel free to use another name. It is the name of this "-> &CELL -> FIELD-MAP -> FILES -> file" which must follow the "-> &CELL -> FIELD-MAP -> FILES" keyword. !W
     /OUTPUT, PRNSOL, lis
     PRNSOL
     /OUTPUT
!W
There is no need to write the electric field to a file since the "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" option is implied when using ANSYS. The PRNSOL file contains the potentials at the nodes. When interpolating between nodes, Garfield needs to know where each of these nodes is located in space. This information is contained in the output of the NLIST command, which should be written to a file called "NLIST.lis". Note the COORD option - without this option, the file would contain additional information which is not used in Garfield, at the price of reduced precision in the node coordinates. Garfield can read files in either format - but the COORD option is recommended. !W
     /OUTPUT, NLIST, lis
     NLIST,,,,COORD
     /OUTPUT
!W
Garfield also needs to know how the nodes are tied into elements. This structure is shown by the ELIST command, of which the output has to be written to a file called "ELIST.lis": !W
     /OUTPUT, ELIST, lis
     ELIST
     /OUTPUT
!W
Optionally, you may transmit the dielectric constants (permittivities) and the electric resistivities to Garfield. Only write this file if your material properties do not have a temperature dependence. The commands for writing the "MPLIST.lis" file are as follows: !W
     /OUTPUT, MPLIST, lis
     MPLIST
     /OUTPUT
!W
If you produce the field maps on operating systems like Windows, control-M will be appended to each line. These need to be removed before the field maps can be read with Garfield. 9. Make Garfield read the field maps. You only need to specify the potential map. The remaining files, ELIST.lis, NLIST.lis and MPLIST.lis are searched for in the same directory. An example follows. Since ANSYS allows the user to use any consistent system of units, the real size of the device can not be found in the field map files. The user therefore has to specify the distance "-> &CELL -> FIELD-MAP -> UNIT". !W
     field-map files "PRNSOL.lis" units=mm ansys-solid-123
!W
!Wol_end In order to compute signals, Garfield needs weighting fields. These are obtained by setting the read-out electrodes to a potential of\ 1 and all other electrodes to a potential of\ 0. Garfield requires the weighting fields and the main field map to share one and the same mesh. To achieve this, follow the above recipe until the end, then clear the existing loads (LSCLEAR), apply new loads and solve without meshing again. This is illustrated in the following example of 3\ strips: !W
  FINISH  
  /CLEAR,START
  /PREP7  
  ! No polynomial elements
  /PMETH,OFF,1
!W 
  ! Set electric preferences
  KEYW,PR_ELMAG,1
  KEYW,MAGELC,1   
!W 
  ! Select element
  ET,1,SOLID123
!W 
  ! Material properties
  MP,PERX,1,1e10  ! Metal
  MP,RSVX,1,0.0   !
  MP,PERX,2,1.0   ! Gas
  MP,PERX,3,4.0   ! Permittivity of FR4
!W 
  ! Construct the structure
  metal = 0.2
  gas = 2
  sub = -1
  BLOCK, -10, -5, -10, 10,     0, metal ! 1: Wide side strip
  BLOCK,  -2, -4, -10, 10,     0, metal ! 2: First signal
  BLOCK,  -1,  1, -10, 10,     0, metal ! 3: 2nd signal
  BLOCK,   2,  4, -10, 10,     0, metal ! 4: 3rd signal
  BLOCK,   5, 10, -10, 10,     0, metal ! 5: Wide side strip
  BLOCK, -10, 10, -10, 10,   sub,     0 ! 6: Substrate
  BLOCK, -10, 10, -10, 10,     0,   gas ! 7: Gas
!W 
  ! Subtract the strips from the gas
  VSBV,  7, 1, , , KEEP   ! 7 \→ 8
  VSBV,  8, 2, , , KEEP   ! 8 \→ 7
  VSBV,  7, 3, , , KEEP   ! 7 \→ 8
  VSBV,  8, 4, , , KEEP   ! 8 \→ 7
  VSBV,  7, 5, , , KEEP   ! 7 \→ 8
!W 
  ! Glue everything together 1 = left wide, 2, 3, 4, 5 = wide, 7 = sub, 8 = gas
  VGLUE, ALL
!W 
  ! Assign material attributes
  VSEL, S, VOLU, , 1, 5 ! Metal strips
  VATT, 1, ,1
  VSEL, S, VOLU, , 7    ! Gas volume
  VATT, 3, ,1
  VSEL, S, VOLU, , 8    ! Substrate
  VATT, 2, ,1
!W 
  ! Voltage boundary conditions on the metal
  VSEL, S, VOLU, , 1, 5 ! All strips at ground
  ASLV, S
  DA, ALL, VOLT, 0
  ASEL, S, LOC, Z, gas  ! Drift electrode
  DA, ALL, VOLT, -1000
  ASEL, S, LOC, Z, sub  ! Back plane
  DA, ALL, VOLT, 0
!W 
  ! Meshing options
  VSEL, S, VOLU, , 8    ! Only mesh the gas
  ASLV, S
!W 
  MSHKEY,0
  SMRT, 4
  VMESH, 1,8
!W 
  ! Solve the field
  /SOLU
  SOLVE   
!W 
  ! Write the solution
  /POST1
  /OUTPUT, field, lis
  PRNSOL
  /OUTPUT
!W 
  ! Change to weighting field boundary conditions for first narrow strip
  /SOLU
  LSCLEAR,ALL
!W 
  VSEL, S, VOLU, , 1
  VSEL, A, VOLU, , 3, 5
  ASLV, S
  DA, ALL, VOLT, 0
!W 
  VSEL, S, VOLU, , 2
  ASLV, S
  DA, ALL, VOLT, 1
!W 
  ASEL, S, LOC, Z, gas
  DA, ALL, VOLT, 0
  ASEL, S, LOC, Z, sub
  DA, ALL, VOLT, 0
!W 
  ! Meshing options
  VSEL, S, VOLU, , 1, 8
  ASLV, S
!W 
  ! Solve the field
  SOLVE   
!W 
  ! Write the solution
  /POST1
  /OUTPUT, weight1, lis
  PRNSOL
  /OUTPUT
!W 
  ! Change to weighting field boundary conditions for 2nd narrow strip
  /SOLU
  LSCLEAR,ALL
!W 
  VSEL, S, VOLU, , 1, 2
  VSEL, A, VOLU, , 4, 5
  ASLV, S
  DA, ALL, VOLT, 0
!W 
  VSEL, S, VOLU, , 3
  ASLV, S
  DA, ALL, VOLT, 1
!W 
  ASEL, S, LOC, Z, gas
  DA, ALL, VOLT, 0
  ASEL, S, LOC, Z, sub
  DA, ALL, VOLT, 0
!W 
  ! Meshing options
  VSEL, S, VOLU, , 1, 8
  ASLV, S
!W 
  ! Solve the field
  SOLVE   
!W 
  ! Write the solution
  /POST1  
  /OUTPUT, weight2, lis
  PRNSOL
  /OUTPUT
!W 
  ! Change to weighting field boundary conditions for last narrow strip
  /SOLU
  LSCLEAR,ALL
!W 
  VSEL, S, VOLU, , 1, 3
  VSEL, A, VOLU, , 5
  ASLV, S
  DA, ALL, VOLT, 0
!W 
  VSEL, S, VOLU, , 4
  ASLV, S
  DA, ALL, VOLT, 1
!W 
  ASEL, S, LOC, Z, gas
  DA, ALL, VOLT, 0
  ASEL, S, LOC, Z, sub
  DA, ALL, VOLT, 0
!W 
  ! Meshing options
  VSEL, S, VOLU, , 1, 8
  ASLV, S
!W 
  ! Solve the field
  SOLVE   
!W 
  ! Write the solution
  /POST1  
  /OUTPUT, weight3, lis
  PRNSOL
  /OUTPUT
!W 
  ! Write the mesh to files
  /OUTPUT, NLIST, lis
  NLIST,,,,COORD
  /OUTPUT
!W 
  /OUTPUT, ELIST, lis
  ELIST
  /OUTPUT
!W 
  /OUTPUT, MPLIST, lis
  MPLIST
  /OUTPUT
!W 
  ! Show the solution
  /EFACET,1   
  PLNSOL, VOLT,, 0
!W
After processing this, the following files should have been created: !Wul_start - field.lis: the main field map with ordinary potentials, - weight1.lis, weight2.lis, weight3.lis: weighting fields for each of the 3 read-out strips, - NLIST.lis: the list of node coordinates, - MPLIST.lis: the material properties, - ELIST.lis: the mesh structure. !Wul_end These files can be processed in Garfield with the following commands: !W
  "-> &CELL"
  Global bin `strips.bin`
  If "-> algebra -> functions -> exist"(bin) Then                // Read binary if it exists
     "-> &CELL -> read-field-map" {bin}
  Else
     "-> &CELL -> field-map" files potential "~/scratch0/field.lis" ...
                     weighting-field "~/scratch0/weight1.lis" label a ...
                     weighting-field "~/scratch0/weight2.lis" label b ...
                     weighting-field "~/scratch0/weight3.lis" label c ...
               units=cm ...
               ansys-solid-123
     "-> &CELL -> save-field-map" {bin}           // Otherwise, create a binary
  Endif
!W 
  "-> &GAS"
  arg-50-eth-50                     // For demonstration only ...
!W 
  "-> &SIGNAL"
  "-> &SIGNAL -> area" -5 -10 -2  5 10 8 x-z
  "-> &SIGNAL -> window" 0 0.0005                   // Sample signals every 0.5 nsec
  "-> &SIGNAL -> select" a b c                      // Read out all electrodes
!W 
  "-> &SIGNAL -> grid" 50                           // Improve granularity
  "-> &SIGNAL -> plot-field" vect ewx, ewy, ewz     // Plot the weighting fields
!W 
  Call "-> Call -> plot_drift_area"
  Call "-> Call -> drift_electron_3"(-2, 0, 1.8) // Drift one electron
  Call "-> Call -> plot_drift_line"
  Call "-> Call -> add_signals"
  Call "-> Call -> plot_end"
!W 
  "-> &SIGNAL -> plot-signals"                      // Show signals
!W
5 QUICKFIELD Recipe to be written. Please refer to http://www.quickfield.com/demo/manual.pdf 5 MAXWELL-11 Specifies that Maxwell version\ 11 has been used to produce the field maps. The recipe for making such field maps is similar to that for earlier versions like "-> &CELL -> FIELD-MAP -> FILES -> format -> Field-Simulator-3D", with the exception that the solids file (with extension .shd) will be called "fields.shd", independent of the mesh iteration and it will be located in a different directory. Beware that files produced with Maxwell Version\ 11 can be read with the interface for earlier versions, and vice-versa, but the results will be incorrect. Be sure therefore to specify the correct Maxwell version on the FIELD-MAP command line. Use of the "-> &CELL -> FIELD-MAP -> DELETE-BACKGROUND" option is mandatory with this format. 3 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: !Wul_start - via an integer: this is interpreted as a sequence number in the sorted list (from small to large) of dielectric constants or the conductivities; - via a real: this is interpreted as a dielectric constant divided by \ε\0\ (i.e. a gas typically has a value close to 1), or a conductivity (a gas usually does not conduct and has a conductivity close to 0); the list of material constants present in the field map is searched for the nearest match; - via a keyword such as SMALLEST. !Wul_end 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 RESET Resets the field map, has the same effect as "-> &CELL -> RESET" "-> &CELL -> RESET -> FIELD-MAP". 3 NOT-X-PERIODIC Specifically states that the field map is not periodic in x. [This is the default.] 3 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 "-> &CELL -> FIELD-MAP -> X-MIRROR-PERIODIC", but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> X-PERIODIC" and X-MIRROR-PERIODIC, but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> X-PERIODIC" and "-> &CELL -> FIELD-MAP -> 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 X-ROTATIONALLY-SYMMETRIC Specifies a rotational symmetry. The field map has to be 2-dimensional. Elements must be used that are suitable for rotational symmetry. Currently, all interfaced finite element programs use the second field map coordinate axis, which we refer to as height, h, as axis of rotational symmetry. We call the first coordinate axis the radius, r. The field map must not contain any element or part of element at r\ \<\ 0. The way the finite element program is informed about the rotational symmetry varies with the programs - consult the documentation. The above is common for all 3 rotational symmetries. The difference is in the way the (r,h) field-map coordinates are computed from the chamber (x,y,z) coordinates. When using X-ROTATIONALLY-SYMMETRIC, the assignment is: !W
  r = \√(y\² + z\²)
  h = x
!W
A chamber can have only one rotational symmetry at the time. [By default, a field map is not assumed to be periodic.] 3 NOT-Y-PERIODIC Specifically states that the field map is not periodic in y. [This is the default.] 3 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 "-> &CELL -> FIELD-MAP -> Y-MIRROR-PERIODIC", but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> Y-PERIODIC" and Y-MIRROR-PERIODIC, but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> Y-PERIODIC" and "-> &CELL -> FIELD-MAP -> 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 Y-ROTATIONALLY-SYMMETRIC Specifies a rotational symmetry. The field map has to be 2-dimensional. Elements must be used that are suitable for rotational symmetry. Currently, all interfaced finite element programs use the second field map coordinate axis, which we refer to as height, h, as axis of rotational symmetry. We call the first coordinate axis the radius, r. The field map must not contain any element or part of element at r\ \<\ 0. The way the finite element program is informed about the rotational symmetry varies with the programs - consult the documentation. The above is common for all 3 rotational symmetries. The difference is in the way the (r,h) field-map coordinates are computed from the chamber (x,y,z) coordinates. When using Y-ROTATIONALLY-SYMMETRIC, the assignment is: !W
  r = \√(x\² + z\²)
  h = y
!W
A chamber can have only one rotational symmetry at the time. [By default, a field map is not assumed to be periodic.] 3 NOT-Z-PERIODIC Specifically states that the field map is not periodic in z. [This is the default.] 3 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 "-> &CELL -> FIELD-MAP -> Z-MIRROR-PERIODIC", but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> Z-PERIODIC" and Z-MIRROR-PERIODIC, but can be "-> &CELL -> FIELD-MAP -> 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 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 "-> &CELL -> FIELD-MAP -> Z-PERIODIC" and "-> &CELL -> FIELD-MAP -> 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 Z-ROTATIONALLY-SYMMETRIC Specifies a rotational symmetry. The field map has to be 2-dimensional. Elements must be used that are suitable for rotational symmetry. Currently, all interfaced finite element programs use the second field map coordinate axis, which we refer to as height, h, as axis of rotational symmetry. We call the first coordinate axis the radius, r. The field map must not contain any element or part of element at r\ \<\ 0. The way the finite element program is informed about the rotational symmetry varies with the programs - consult the documentation. The above is common for all 3 rotational symmetries. The difference is in the way the (r,h) field-map coordinates are computed from the chamber (x,y,z) coordinates. When using Z-ROTATIONALLY-SYMMETRIC, the assignment is: !W
  r = \√(x\² + y\²)
  h = z
!W
A chamber can have only one rotational symmetry at the time. [By default, a field map is not assumed to be periodic.] 3 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 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 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 INTERPOLATE-ELECTRIC-FIELD Requests the calculation of the electric field by interpolating in the electric field tables as provided by the finite element program. This interpolation is meaningful only if the finite element program outputs, for a single node, as many electric field vectors as there are elements to which the node belongs. The reason for this is that, contrary to the potential, the electric field is as a rule discontinuous across element boundaries. This discontinuity exists even if \ε is the same on both sides. Many finite element programs output only one electric field vector per node. When using these, "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" should be selected. This option is currently only active for hexahedral field maps. It is automatically set for several field map formats, such as those produced by Ansoft programs.. [This option is default.] 3 COMPUTE-ELECTRIC-FIELD Requests the calculation of the electric field using the potentials at the nodes. This technique works by taking the derivatives of the shape functions to the natural coordinates, multiplied by the Jacobian of the transformation of the natural coordinates to user coordinates. For elements with use isoparametric coordinates, which is nearly always the case, this calculation entails little or no overhead since the Jacobian is reused from the iterative calculation of the local coordinates. These derivatives are reliable also in case the nodes happen to lie on an interface between materials of different \εs. This option is automatically switched on when using "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123", "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-plane-121" and several other finite element programs. [This option is not default.] 3 DELETE-BACKGROUND Removes the background from the field map. Background elements are usually pieces of conductors, in which there is no field. Option active with Maxwell Field Simulator 3D and ANSYS: !Wul_start - Maxwell: This option relies on the .shd project file. This file is produced by Maxwell as part of its regular output. In newer versions, it is sometimes written to a different directory from the mesh files. Garfield only looks for this file in the directory of the mesh files and you may therefore have to copy the file. - ANSYS: Elements are eliminated if the resistivity of the material is strictly equal to 0. The resistivity is obtained from an MPLIST file stored in the same directory as the field map. No elements are deleted if no such file is found. Temperature-dependent resistivities are not processed. !Wul_end Note: this option is implicit with the "-> &CELL -> FIELD-MAP -> FILES -> format -> MAXWELL-11" format. [This option is on by default.] 3 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 OFFSET Requests the field map be shifted. By default, Garfield uses the coordinate system from the finite element program. As a rule, this doesn't lead to limitations. However, in case overlays an analytic field with a finite element field, it may happen that the fields need to be aligned. Such an alignment can be obtained with the OFFSET option. If you specify an offset of (xoff,yoff,zoff), then Garfield will interpolate the field map at (x-xoff,y-yoff,z-zoff) when it needs a field at (x,y,z). All 3\ coordinates should be specified, even if the field map is 2-dimensional. [By default, the 3 offsets are set to 0. The offsets are saved with the binary field maps.] 3 UNIT The distance unit used in the field map. The unit must be one of the following: !Wul_start - MICROMETRE or MICRON or MUM - MILLIMETRE or MM - CENTIMETRE or CM - METRE or M !Wul_end This information is only used for "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2d-linear", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-2d-quadratic", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3d-linear", "-> &CELL -> FIELD-MAP -> FILES -> format -> COMSOL-3d-quadratic", "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123" and "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-plane-121" field maps. [By default, the centimetre is assumed as length unit.] 3 PLOT-MAP Requests the materials to be shown in plots of the chamber. Materials are distinguished by their dielectric constant or their conductivity. A map of either of these must therefore be available for this option to have effect. Maps of the dielectric constant an the conductivity can be supplied as such. A map of the dielectric constant will automatically be computed also if maps of both E and B are present. The material with the smallest dielectric constant is shown with representation "-> graphics -> REPRESENTATION -> item -> MATERIAL-1". The medium with the next highest dielectric constant with "-> graphics -> REPRESENTATION -> item -> MATERIAL-2" etc. The drift medium is never shown. Elements of a 2D field map are only shown in "-> &FIELD -> AREA -> X-Y" views and in "-> &FIELD -> AREA -> CUT" views at a constant z. The cross sections of the viewing "-> &FIELD -> AREA -> plane" with the elements of a 3D field map are shown in "-> &FIELD -> AREA -> X-Y", "-> &FIELD -> AREA -> X-Z", "-> &FIELD -> AREA -> Y-Z" and "-> &FIELD -> AREA -> CUT" views, but not in "-> &FIELD -> AREA -> 3D" views. Field maps do not usually cover areas filled with conducting material since there is no field inside. To visualise these, one has to enter them manually with the "-> &CELL -> SOLIDS" command. SOLIDS doesn't interfere with PLOT-MAP. This option can also be switched on and off with the "-> &FIELD -> AREA -> PLOT-MAP" option of the "-> &FIELD -> AREA" command. [By default, the map is shown.] 3 HISTOGRAM-MAP Requests histograms to be plotted of the aspect ratio (i.e. the ratio of the largest and the smallest vertex separation) and of the surface or volume of the elements in the mesh. Elements with large aspect ratios can be a sign that the mesh is of poor quality. One should then consider using the so-called virtual-volumes technique to constrain the mesh elements. Elements with a very large volume or surface are likely to cause problems when transporting particles since the finite element method only guarantees continuity of the potential, not of the electric field. With large elements, the discontinuity across element boundaries is likely to be large. Switching on this option further enables checks on the elements to be carried out, in particular a search for irregular element degeneracy. [These histograms are not made by default.] 2 GET Retrieves a compact format cell dataset written by "-> &CELL -> 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: !W
  GET "-> &CELL -> GET -> file" ["-> &CELL -> GET -> member"]
!W
Examples: !W
  get "~rjd/Garfield/Test/cell.dat"
  get 'disk$zp:[veenhof.garfield]cell'
!W
The first example is typical for a Unix system, note the use of double "-> introduction -> quotes" to preserve the case. The second example, for Vax, will read the first member of type CELL from the library with file name "CELL.DAT". The extension .DAT is the default setting of the "-> dataset -> DEFAULT" command, the upper case is the result of using single quotes. Libraries may contain members of other types - but only members of type CELL will be considered by GET. 3 file The name of the "-> dataset -> structure -> file" that contains the cell description. 3 member The name of the "-> dataset -> structure -> member" that you wish to retrieve. 2 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: !W
  GRAVITY  x y z
!W
Example: !W
  gravity  0 0 1
!W
This makes the wires run vertical, the default. In this situation, gravity does not produce a wire sag. 2 NEBEM Sets parameters used by the interface to neBEM and inside neBEM when discretising the primitives and thus forming the elements. Format: !W
  NEBEM ["-> &CELL -> NEBEM -> ANGULAR-TOLERANCE" eps_angle] ...
        ["-> &CELL -> NEBEM -> DISTANCE-TOLERANCE" eps_distance] ...
        ["-> &CELL -> NEBEM -> LU-INVERSION" | "-> &CELL -> NEBEM -> SVD-INVERSION"] ...
        ["-> &CELL -> NEBEM -> MAXIMUM-ELEMENTS" max] ...
        ["-> &CELL -> NEBEM -> MINIMUM-ELEMENTS" min] ...
        ["-> &CELL -> NEBEM -> NEW-MODEL" | "-> &CELL -> NEBEM -> REUSE-MODEL" ] ...
        [NOKEEP-INVERTED-MATRIX | "-> &CELL -> NEBEM -> KEEP-INVERTED-MATRIX"] ...
        ["-> &CELL -> NEBEM -> PERIODIC-COPIES" copies] ...
        ["-> &CELL -> NEBEM -> QUALITY-THRESHOLD" qthr] ...
        ["-> &CELL -> NEBEM -> SIZE-THRESHOLD" sthr] ...
        ["-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" target] ...
        ["-> &CELL -> NEBEM -> X-PERIODIC-COPIES" copies] ...
        ["-> &CELL -> NEBEM -> Y-PERIODIC-COPIES" copies] ...
        ["-> &CELL -> NEBEM -> Z-PERIODIC-COPIES" copies]
!W
Example: !W
  nebem min-elem 2 max-elem 10 target 0.1
!W
3 ANGULAR-TOLERANCE Parameter in the interface to neBEM which is used to determine whether two surface panels are parallel or not. [Default value: 10^-6 radian.] 3 DISTANCE-TOLERANCE Parameter in the interface to neBEM which determines whether two points are treated as identical or not. Numerous warnings and error messages from the PLAOVL procedure are an indication that this parameter has an inappropriate value. [Default value: 10^-6 cm.] 3 LU-INVERSION Requests solving the capacity equation through LU factorisation. [The is default.] 3 SVD-INVERSION Requests solving the capacity equation through singular value decompsition (SVD factorisation). This technique is superior where the charges on several panels have nearly identical effects. This seems to happen in cylindrical structures. The differences are marginal in box-like layouts. SVD is substantially slower than LU. E.g. for a matrix size of 4000, SVD takes nearly ten times more time than LU. The difference is significant only for structures with several 1000 or more elements. [The default is "-> &CELL -> NEBEM -> LU-INVERSION".] 3 MAXIMUM-ELEMENTS Corresponds to neBEM parameter \MaxNbElementsOnLength\. Largest number of elements produced along either axis of a single primitive. There is no upper limit but CPU time consumption and memory requirements rise faster than linear with the number of elements in the model. If the minimum exceeds the maximum, then the values will be interchanged. [Default: 10] 3 MINIMUM-ELEMENTS Corresponds to neBEM parameter \MinNbElementsOnLength\. Smallest number of elements produced along either axis of a single primitive. The smallest value allowed is 1. If the minimum exceeds the maximum, then the values will be interchanged. [Default: 1] 3 NEW-MODEL Corresponds to neBEM parameters \NewModel, NewMesh, NewBC\ and \NewPP\ all being set to 1 (true). Instructs neBEM to obtain the geometric and potential data from Garfield, to calculate the influence matrix and to solve the capacitance equation. [This is default] 3 REUSE-MODEL Corresponds to neBEM parameters \NewModel, NewMesh, NewBC\ being set to 0 (false) but \NewPP\ set to 1 (true). Instructs neBEM to obtain the geometric and potential data from Garfield, but to recover the influence matrix and the element charges from files that have been written during an earlier run. The user must ensure that the geometry, influence matrix and charges are coherent. This means in practice that the calculations must be run in the same directory as an earlier run with the "-> &CELL -> NEBEM -> NEW-MODEL" flag in effect, with identical boundary conditions. There is no option or command to request storing the model: neBEM always stores the model. If the inverted influence matrix (capacitance matrix) has been stored, in response to specifying the "-> &CELL -> NEBEM -> KEEP-INVERTED-MATRIX" option.then it too will be retrieved when re-specifying this option. [This is not default.] 3 KEEP-INVERTED-MATRIX Requests that neBEM store and retrieve the inverted influence matrix (capacitance matrix). This matrix is currently needed only for the calculation of weighting fields. This matrix is large. The flag must be set both during the initial run that computes and writes the element charges, and during the runs in which these charges are retrieved by means of the "-> &CELL -> NEBEM -> REUSE-MODEL" option. [By default, the inverted matrix is neither stored nor retrieved.] 3 PERIODIC-COPIES Sets the number of periodic repetitions that neBEM will use when dealing with periodic cells. This command does not make the cell periodic. You have to use the "-> &CELL -> PERIODICITY" command to achieve that.. neBEM currently does not have explicit periodic Green's functions for periodic configurations. It approximates these with the sum of a series of periodic copies of the non-periodic Green's function. The series runs from \-copies\ to \copies\. Since the Green's function are expensive to calculate, it is advisable to choose a low number of copies. In 3 dimensions, the series converges rapidly. neBEM allows this parameter to be set individually for each primitive, but the Garfield interface stores only one value, common to all primitives. The number of periodic copies can be set indivually along each axis, or collectively for all 3 axes. [Default: 5, which corresponds to having in all 11 copies.] 3 QUALITY-THRESHOLD Parameter in the interface to neBEM which places an upper limit on the slenderness of triangular primitives. The quality is defined as the ratio of the longest side over the shortest side. This parameter currently only leads to reduction of the overall size of sharp-angled triangles, it does not yet stop them from being created. The minimum quality must be larger than 1. [Default setting: 150.] 3 SIZE-THRESHOLD Parameter in the interface to neBEM which limits the size of triangular primitives passed to neBEM. The size is expressed as a fraction of the overall model dimensions. This parameter has currently not effect. A similar effect can be obtained by setting discretisation sizes on the solids and also by using the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE", "-> &CELL -> NEBEM -> MINIMUM-ELEMENTS" and "-> &CELL -> NEBEM -> MAXIMUM-ELEMENTS" parameters. [Default setting: 0.001] 3 TARGET-ELEMENT-SIZE Corresponds to neBEM parameter \ElementLengthRqstd\. Target linear size of the elements, measured along their edges, produced by neBEM's discretisation process. The element sizes are if needed increased or decreased to respect the "-> &CELL -> NEBEM -> MINIMUM-ELEMENTS" and "-> &CELL -> NEBEM -> MAXIMUM-ELEMENTS" parameters. If specified before the "-> &CELL -> SOLIDS" command is issued, then the value will be used as default for all solids that are entered. The value can be overridden on any individual solid. If specified after the "-> &CELL -> SOLIDS" command, then the value applies only to those faces for which the discretisation length has been is specified as "automatic". [Default: 50 micron.] 3 X-PERIODIC-COPIES Sets the number of periodic repetitions that neBEM will use when dealing with periodic cells. This command does not make the cell periodic. You have to use the "-> &CELL -> PERIODICITY" command to achieve that.. neBEM currently does not have explicit periodic Green's functions for periodic configurations. It approximates these with the sum of a series of periodic copies of the non-periodic Green's function. The series runs from \-copies\ to \copies\. Since the Green's function are expensive to calculate, it is advisable to choose a low number of copies. In 3 dimensions, the series converges rapidly. neBEM allows this parameter to be set individually for each primitive, but the Garfield interface stores only one value, common to all primitives. The number of periodic copies can be set indivually along each axis, or collectively for all 3 axes. [Default: 5, which corresponds to having in all 11 copies.] 3 Y-PERIODIC-COPIES Sets the number of periodic repetitions that neBEM will use when dealing with periodic cells. This command does not make the cell periodic. You have to use the "-> &CELL -> PERIODICITY" command to achieve that.. neBEM currently does not have explicit periodic Green's functions for periodic configurations. It approximates these with the sum of a series of periodic copies of the non-periodic Green's function. The series runs from \-copies\ to \copies\. Since the Green's function are expensive to calculate, it is advisable to choose a low number of copies. In 3 dimensions, the series converges rapidly. neBEM allows this parameter to be set individually for each primitive, but the Garfield interface stores only one value, common to all primitives. The number of periodic copies can be set indivually along each axis, or collectively for all 3 axes. [Default: 5, which corresponds to having in all 11 copies.] 3 Z-PERIODIC-COPIES Sets the number of periodic repetitions that neBEM will use when dealing with periodic cells. This command does not make the cell periodic. You have to use the "-> &CELL -> PERIODICITY" command to achieve that.. neBEM currently does not have explicit periodic Green's functions for periodic configurations. It approximates these with the sum of a series of periodic copies of the non-periodic Green's function. The series runs from \-copies\ to \copies\. Since the Green's function are expensive to calculate, it is advisable to choose a low number of copies. In 3 dimensions, the series converges rapidly. neBEM allows this parameter to be set individually for each primitive, but the Garfield interface stores only one value, common to all primitives. The number of periodic copies can be set indivually along each axis, or collectively for all 3 axes. [Default: 5, which corresponds to having in all 11 copies.] 2 OPTIONS Selects both cell related as well as top level "-> OPTIONS". Format: !W
  OPTIONS [NOLAYOUT | "-> &CELL -> OPTIONS -> LAYOUT"] ...
          [NOCELL-PRINT | "-> &CELL -> OPTIONS -> CELL-PRINT"] ...
          [NOTISOMETRIC | "-> &CELL -> OPTIONS -> ISOMETRIC"] ...
          [NOWIRE-MARKERS | "-> &CELL -> OPTIONS -> WIRE-MARKERS"] ...
          [NOCHARGE-CHECK | "-> &CELL -> OPTIONS -> CHARGE-CHECK"] ...
          [NODIPOLE-TERMS | "-> &CELL -> OPTIONS -> DIPOLE-TERMS"]
!W
Example: !W
  OPT C-PR
!W
Requests a summary of the elements present in the cell. 3 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 "-> &FIELD -> SELECT". The same listing can be obtained in the optimisation section using the "-> &OPTIMISE -> PRINT-CELL" command. [This option is initially off but its setting is remembered from one cell section to the next.] 3 DIPOLE-TERMS Requests dipole terms be included for each of the wires. Dipole terms are significant for thick wires that are nearly at the ambient potential, such as gate wires in TPCs. This can be investigated with the "-> &FIELD -> MULTIPOLE-MOMENTS" command. Currently, dipole terms are available only for potential types A, B1X, B1Y, B2X and B2Y. Contact the author if you need dipole terms for other potentials. [Dipole terms are by default not included.] 3 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 next to the wires unless the "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is active. The cell is plotted using the "-> &FIELD -> AREA -> X-Y" or "-> &FIELD -> AREA -> R-PHI" projection, as appropriate. To visualise the layout in other projections, use either the "-> Call -> PLOT_FIELD_AREA" or the "-> Call -> PLOT_DRIFT_AREA" procedure in the field respectively drift section. 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 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. In those sections, one can obtain an isometric view by using the "-> &FIELD -> AREA -> 3D" projection. Using this option in conjunction with a non-square "-> graphics -> VIEWPORT" is not meaningful. [This option is initially off, but its setting is remembered from one cell section to the next.] 3 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, optimisation, drift and signal sections. The type of marker used for a wire depends on the "-> &CELL -> ROWS -> label" that you have assigned to the wire in the "-> &CELL -> ROWS" listing. Each marker can be adjusted individually via the representations mechanism. The correspondence between labels and "-> graphics -> REPRESENTATION" is as follows: !Wtable_start !T+P +P . ---------------------------------------------------------------- Label Representation ---------------------------------------------------------------- S "-> graphics -> REPRESENTATION -> item -> S-WIRES" P "-> graphics -> REPRESENTATION -> item -> P-WIRES" C "-> graphics -> REPRESENTATION -> item -> C-WIRES" other "-> graphics -> REPRESENTATION -> item -> OTHER-WIRES" ---------------------------------------------------------------- !Wtable_end All wires are shown with the representation "-> graphics -> REPRESENTATION -> item -> WIRES" when the option is off. The "-> &CELL -> OPTIONS -> LAYOUT" plot does not contain alphabetic wire labels if this option is active. [This option is initially off, but its setting is remembered from one cell section to the next.] 3 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.] 2 PERIODICITY States that the chamber has infinite periodicity in a direction. Use two or more of these lines if your chamber has multiple periodicity. Chambers which have a repetitive structure over a considerable distance, as for instance in multiwire proportional chambers, should be declared periodic if you wish to enhance the numerical precision of the calculations. You will also gain CPU time by doing so. There are however instances where you may wish to enter explicit copies of the cell, increasing the periodicity length accordingly: !Wul_start - Isochrons are computed for only one copy of each wire. This is merely an aesthetic disadvantage since the isochrons are identical for all copies. - Drift-lines reaching periodic copies of a wire or a plane are assigned a "-> &DRIFT -> methods -> status" code which does not tell which copy has been hit. One can compute this information from the end point, but it is simpler to enter explicitly the copies which are likely to be hit. - All copies of a wire undergo the same electrostatic (and gravitational) sag, hence the so-called zig-zag motion is not visible unless at least 2 copies of each wire are explicitly entered. - The difference between the signals on the various copies of a wire is taken into account, but the signal on only one copy is computed. To study signals on neighbouring wires, one therefore has to enter at least 2, usually 3-5, copies of the chamber. !Wul_end This statement is only used with chambers constructed from wires, planes and solids. If the field in the chamber is taken from a field map, options such as "-> &CELL -> FIELD-MAP -> X-PERIODIC" of the "-> &CELL -> FIELD-MAP" command should be used instead. In chambers modelled using neBEM, periodicity-related parameters can be set using the "-> &CELL -> NEBEM" command. Format: !W
  PERIODICITY "-> &CELL -> PERIODICITY -> direction" = "-> &CELL -> PERIODICITY -> length" ["-> &CELL -> PERIODICITY -> REGULAR" | "-> &CELL -> PERIODICITY -> MIRROR"]
!W
Example: !W
  PERIOD X=1
!W
3 direction The direction in which the cell is infinitely repeated. Can have one of the following 3 values: !Wtable_start !T+P + + . ----------------------------------------------------------------- Direction Meaning Coordinate system ----------------------------------------------------------------- X Cell repeats in x Cartesian Y Cell repeats in y Cartesian Z Cell repeats in z - PHI Axial periodicity around the origin Polar or Tube ----------------------------------------------------------------- !Wtable_end 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 in which an r-periodicity would be equivalent to an x-periodicity with non-constant intervals. This is technically difficult to deal with. Contact the author if there is a genuine need for such a periodicity. Periodicity in z is only allowed with neBEM field calculations, not in wire and planes chambers. 3 length The length of one full period, expressed in cm for x and y periodicities and in degrees for periodicity in \φ. 3 REGULAR Indicates that all periodic copies of the basic cell are identical. This is the only type of periodicity permitted in cells constructed of wires and planes. This type of periodicity is recognised by neBEM. [If periodicity is requested, then it will by default have this type of periodicity.] 3 MIRROR Indicates that odd periodic copies of the basic cell are mirror images of even periodic copies. This is the type of periodicity is not permitted in cells constructed of wires and planes. This type of periodicity is recognised by neBEM. [If periodicity is requested, then it will by default be regular.] 2 PLANE Specifies an infinite equipotential plane in at constant x, y or \φ or a circular plane with constant r. Note that one is not allowed to put a wire at the centre of a circular plane. Wires inside a circular plane, whether at the centre or not, are handled by "-> &CELL -> TUBE" geometries. Planes are not compatible with a TUBE geometry. To generate a pie wedge, use a plane at constant r and two planes at constant \φ. Format: !W
  PLANE "-> &CELL -> PLANE -> direction" "-> &CELL -> PLANE -> coordinate" ...
        [V "-> &CELL -> PLANE -> potential"] ...
        [LABEL "-> &CELL -> PLANE -> label"] ...
        [{X-"-> &CELL -> PLANE -> STRIP" | Y-"-> &CELL -> PLANE -> STRIP" | R-"-> &CELL -> PLANE -> STRIP" | PHI-"-> &CELL -> PLANE -> STRIP" | Z-"-> &CELL -> PLANE -> STRIP"} "-> &CELL -> PLANE -> strip_min" "-> &CELL -> PLANE -> strip_max" ...
           [GAP "-> &CELL -> PLANE -> gap"] [LABEL "-> &CELL -> PLANE -> strip_label"]]
!W
Examples: !W
  pl x=-1, V=1000
  plane phi=30
!W
3 direction Specifies which coordinate is constant along the plane. Can have one of the following 4 values: !Wtable_start !T+P + + . ------------------------------------------------------------ Direction Meaning Coordinate system ------------------------------------------------------------ X Plane parallel with the y-axis Cartesian Y Plane parallel with the x-axis Cartesian R Circular plane Polar PHI Plane through the origin Polar ------------------------------------------------------------ !Wtable_end 3 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 potential Optional indication of the potential, in Volt, of the plane. [Default: an earthed plane, at 0\ V.] 3 label A label by which the plane can be referenced in "-> &FIELD -> 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.] 3 STRIP Anticipates read-out of a part of the plane. Signals in strips are computed with weighting fields that are exclusively valid for parallel plate chambers without wires. This can perhaps most easily be seen in an MWPC where the weighting field (orange in the figure) of the strip (in red, covering -0.1\ <\ x\ <\ 0.1\ cm) is not influenced by the wires (purple) - while in reality, the influence of the wires is of course highly significant. !W The reason for this limitation is that no exact weighting fields for strips are known for general wire-plane layouts. Should expressions be known for the particular case that interests you, then these can of course be added on demand. See the "-> &OPTIMISE -> FIELD-MAP -> weighting_field" example for the "-> &OPTIMISE -> FIELD-MAP" command of the optimisation section for a method to address this using the finite element technique. Subdivisions are permitted as follows: !Wtable_start !T+P + + . ---------------------------------------- Subdivision Permitted with Unit ---------------------------------------- R-STRIP PLANE PHI=... cm PHI-STRIP PLANE R=... degrees X-STRIP PLANE Y=... cm Y-STRIP PLANE X=... cm Z-STRIP all planes cm ---------------------------------------- !Wtable_end 3 strip_min Indicates the starting point of the strip. The location should be given in degrees for \φ-sectors, in cm for all other strips. [Mandatory parameter, no default provided.] 3 strip_max Indicates the end point of the strip. The location should be given in degrees for \φ-sectors, in cm for all other strips. [Mandatory parameter, no default provided.] 3 strip_label A label by which the strip can be referenced in "-> &FIELD -> SELECT" statements, when computing signals induced in the strip 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 strip are only computed if the strip can be selected, and this can only be done if the strip has a label. [By default, no label is assigned to a strip.] 3 gap Indicates the gap width to be used when computing the weighting field for the strip. The gap is specified in cm for strips in x-, r- and y-planes, and in degrees for strips in \φ-planes. [By default, this is taken to be the distance to the parallel plane, if there is one, otherwise the distance from the plane to which the strip belongs to the nearest electrode.] 3 representations The planes will be displayed using the "-> graphics -> REPRESENTATION -> item -> PLANES" representation. Strips, if any, are shown with the "-> graphics -> REPRESENTATION -> item -> STRIPS" representation. 2 READ-FIELD-MAP Reads a binary field map file, written with "-> &CELL -> SAVE-FIELD-MAP". This command is executed immediately. Once the command has completed, you can use the "-> &CELL -> 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: !W
  READ-FIELD-MAP file ...
                 ["-> &CELL -> READ-FIELD-MAP -> DRIFT-MEDIUM" {SMALLEST-EPSILON | ...
                                SECOND-SMALLEST-EPSILON | ...
                                n | ...
                                SECOND-LARGEST-EPSILON | ...
                                LARGEST-EPSILON | ...
                                \ε}] ...
                 ["-> &CELL -> READ-FIELD-MAP -> NOT-X-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> X-PERIODIC" | ...
                      "-> &CELL -> READ-FIELD-MAP -> X-MIRROR-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> X-AXIALLY-PERIODIC"] ...
                 ["-> &CELL -> READ-FIELD-MAP -> NOT-Y-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> Y-PERIODIC" | ... 
                      "-> &CELL -> READ-FIELD-MAP -> Y-MIRROR-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> Y-AXIALLY-PERIODIC"] ...
                 ["-> &CELL -> READ-FIELD-MAP -> NOT-Z-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> Z-PERIODIC" | ... 
                      "-> &CELL -> READ-FIELD-MAP -> Z-MIRROR-PERIODIC" | "-> &CELL -> READ-FIELD-MAP -> Z-AXIALLY-PERIODIC"] ...
                 ["-> &CELL -> READ-FIELD-MAP -> LINEAR" | "-> &CELL -> READ-FIELD-MAP -> QUADRATIC" | "-> &CELL -> READ-FIELD-MAP -> CUBIC"] ...
                 ["-> &CELL -> READ-FIELD-MAP -> INTERPOLATE-ELECTRIC-FIELD" | "-> &CELL -> READ-FIELD-MAP -> COMPUTE-ELECTRIC-FIELD"] ...
                 ["-> &CELL -> READ-FIELD-MAP -> PLOT-MAP" | NOPLOT-MAP] ...
                 [NOHISTOGRAM-MAP | "-> &CELL -> READ-FIELD-MAP -> HISTOGRAM-MAP"]
!W
Example: !W
  "-> &CELL"
  "-> &CELL -> cell-identifier" "Micromegas"
  "-> Global" path=`/afs/cern.ch/exp/compass/scratch/d02/megas/Maxwell/mic3.pjt/`
  "-> Call" "-> 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
!W
If a binary field map exists, the map is read. Otherwise the field maps are read in their original format. The periodicity options need not be repeated: they are stored in the binary field map. 3 DRIFT-MEDIUM See the description of the "-> &CELL -> FIELD-MAP -> DRIFT-MEDIUM" option of the "-> &CELL -> FIELD-MAP" command. 3 NOT-X-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> NOT-X-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 X-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> X-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 X-MIRROR-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> X-MIRROR-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 X-AXIALLY-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> X-AXIALLY-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 NOT-Y-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> NOT-Y-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Y-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Y-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Y-MIRROR-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Y-MIRROR-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Y-AXIALLY-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Y-AXIALLY-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 NOT-Z-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> NOT-Z-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Z-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Z-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Z-MIRROR-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Z-MIRROR-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 Z-AXIALLY-PERIODIC See the description of the "-> &CELL -> FIELD-MAP -> Z-AXIALLY-PERIODIC" option of the "-> &CELL -> FIELD-MAP" command. 3 LINEAR See the description of the "-> &CELL -> FIELD-MAP -> LINEAR" option of the "-> &CELL -> FIELD-MAP" command. The order of the field map can not be increased when reading back a binary map. 3 QUADRATIC See the description of the "-> &CELL -> FIELD-MAP -> QUADRATIC" option of the "-> &CELL -> FIELD-MAP" command. The order of the field map can not be increased when reading back a binary map. 3 CUBIC See the description of the "-> &CELL -> FIELD-MAP -> CUBIC" option of the "-> &CELL -> FIELD-MAP" command. The order of the field map can not be increased when reading back a binary map. 3 INTERPOLATE-ELECTRIC-FIELD See the description of the "-> &CELL -> FIELD-MAP -> INTERPOLATE-ELECTRIC-FIELD" option of the "-> &CELL -> FIELD-MAP" command. 3 COMPUTE-ELECTRIC-FIELD See the description of the "-> &CELL -> FIELD-MAP -> COMPUTE-ELECTRIC-FIELD" option of the "-> &CELL -> FIELD-MAP" command. 3 PLOT-MAP See the description of the "-> &CELL -> FIELD-MAP -> PLOT-MAP" option of the "-> &CELL -> FIELD-MAP" command. 3 HISTOGRAM-MAP See the description of the "-> &CELL -> FIELD-MAP -> HISTOGRAM-MAP" option of the "-> &CELL -> FIELD-MAP" command. 2 RESET Resets either fully or selectively the cell data entered so far. A full reset is performed in the absence of arguments. Format: !W
  RESET ["-> &CELL -> RESET -> COORDINATES"] ...
        ["-> &CELL -> RESET -> DIELECTRICA"] ...
        ["-> &CELL -> RESET -> DEFINITIONS"] ...
        ["-> &CELL -> RESET -> FIELD-MAP"] ...
        ["-> &CELL -> RESET -> PERIODICITIES"] ...
        ["-> &CELL -> RESET -> PLANES"] ...
        ["-> &CELL -> RESET -> ROWS" or WIRES] ...
        ["-> &CELL -> RESET -> SOLIDS"] ...
        ["-> &CELL -> RESET -> TUBE"]
!W
Example: !W
  RESET
!W
3 COORDINATES Resets the type of coordinate system being used. This should only be needed when switching between Cartesian, polar and tube coordinates. 3 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 DIELECTRICA Removes all dielectric media from the cell. 3 FIELD-MAP Deletes the field maps. The effect of RESET FIELD-MAP is the same as FIELD-MAP "-> &CELL -> FIELD-MAP -> RESET". 3 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 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 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 SOLIDS Deletes the solids. 3 TUBE Deletes the tube, if entered. Also resets the coordinate system flag associated with tube coordinates. 3 WIRES Synonym of "-> &CELL -> ROWS". 2 ROWS ROWS is used to enter the wires in a cell that may further contain "-> &CELL -> plane"s or a "-> &CELL -> tube" and which can also have "-> &CELL -> periodicity". The wires in such cells are assumed to have infinite length (except when calculating the sage) and a diameter that is small compared to the distance to other electrodes. Furthermore, all wires are parallel with the z-axis. If the wires are thick, short or non-parallel, then neBEM should be used to compute the field. For thin wires, "-> &CELL -> SOLIDS -> WIRE" solids should be used while "-> &CELL -> SOLIDS -> CYLINDER" solids are appropriate for thick wires. The following properties of the wires can be entered: !Wul_start - a label that identifies the kind of wire (e.g. S for a sense wire); - the position of the wire; - the potential applied to the wire; - the diameter of the wire; - the length of the wire; - the weight with which the wire was stretched; - the density of the material of which the wire is made. !Wul_end 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 \φ 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 "-> &CELL -> ROWS -> loop-variable" I which automatically assumes a series of values. One may use control structures ("-> If_block", "-> If_line", "-> Do", "-> 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: !W
  ROWS ["-> &CELL -> ROWS -> CARTESIAN" | "-> &CELL -> ROWS -> POLAR" | "-> &CELL -> ROWS -> TUBE"]
  row
  ...
  row
  (blank line)
!W
Format of the rows: !W
  "-> &CELL -> ROWS -> label" "-> &CELL -> ROWS -> n" "-> &CELL -> ROWS -> diameter" "-> &CELL -> ROWS -> x" "-> &CELL -> ROWS -> y" ["-> &CELL -> ROWS -> V" ["-> &CELL -> ROWS -> weight" ["-> &CELL -> ROWS -> length" ["-> &CELL -> ROWS -> density"]]]]
!W
Examples: !W
  ROWS
  s * * 0 0 1000
  p * * 0 1 -2000
  p * * 0 -1 -2000
!W
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. !W
  ROWS
  S * * 0 0 1000
  P 2 * -1+i*2 -1+i*2 -2000
!W
This examples shows how the same cell can be entered using the loop variable. !W
  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*"-> algebra -> functions -> entier"(i/2) Then
         P * * {r*"-> algebra -> functions -> cos"(phi), r*"-> algebra -> functions -> sin"(phi), -i*10}
     Else
         S * * {r*"-> algebra -> functions -> cos"(phi), r*"-> algebra -> functions -> sin"(phi), +i*10}
     Endif
  Enddo
!W
This, artificial, example illustrates the use of "-> Global" variables, a "-> 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 CARTESIAN States that the wires will be entered using "-> &CELL -> methods -> coordinate_system -> Cartesian" (x,y) coordinates. 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 POLAR States that the wires will be entered using "-> &CELL -> methods -> coordinate_system -> Polar" (r,\φ) coordinates with r in cm and \φ 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 "-> &CELL -> 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 \φ. Periodicity in \φ 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 displaying the results. This keyword need not be specified if the cell is already established to be in polar coordinates, for instance if a \φ 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 TUBE "-> &CELL -> methods -> coordinate_system -> Tube" coordinates are 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 \φ 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 "-> &CELL -> 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 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 "-> &FIELD -> 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 n The number of wires in the row. Each wire in such a row will have the same status as if it were entered on a separate line. Entering wires in the form of rows has no incidence on the choice of "-> &CELL -> methods -> potential_function" used for the chamber. The number of wires may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables but you may, of course, not use the "-> &CELL -> ROWS -> loop-variable" I. [Default: 1, i.e. a single wire]. 3 diameter The diameter of the wires in the row in cm. Since the electric 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 "-> &FIELD -> MULTIPOLE-MOMENTS" instruction to investigate the need for higher order terms to describe the field around the wire. Consider using the "-> &CELL -> OPTIONS -> DIPOLE-TERMS" in case dipole terms are thought to be important. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I in the expression if you wish. [Default: 0.01\ cm, i.e. 100\ \μm]. 3 x The x- or r-position in cm of the wires in the row. If the cell is described in "-> &CELL -> methods -> coordinate_system -> Cartesian" or "-> &CELL -> methods -> coordinate_system -> Tube" coordinates, then (x,y) coordinates should be used for the wire location. The wire coordinates should be given in (r,\φ) format for "-> &CELL -> methods -> coordinate_system -> Polar" cells. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I 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 !W
  1+I
!W
[Default: 0\ cm.] 3 y The y- or \φ-position in cm or degrees of the wires in the row. If the cell is described in "-> &CELL -> methods -> coordinate_system -> Cartesian" or "-> &CELL -> methods -> coordinate_system -> Tube" coordinates, then (x,y) coordinates should be used for the wire location. The wire coordinates should be given in (r,\φ) format for "-> &CELL -> methods -> coordinate_system -> Polar" cells. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I 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 !W
  (1+I)^2
!W
[Default: 0\ cm, \φ should be in degrees.] 3 V The potential of the wires in the row in V. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I to construct symbolic expressions for the locations 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 !W
  1000+entier(i/2)*1000
!W
[Default: 0\ cm.] 3 weight The mass in g of the weight used to stretch the wires during the assembly. Used by the "-> &OPTIMISE -> FORCES" command to estimate the wire displacement under gravitational and electrostatic forces. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I to construct symbolic expressions. [Default: 50\ grams.] 3 length The length of the wires in cm. Used by the "-> &OPTIMISE -> FORCES" command to estimate the wire displacement under gravitational and electrostatic forces. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I to construct symbolic expressions. Note that the length of the wires has no impact on the fields in the chamber. Fields in chambers that are made up of wires and planes are truly 2-dimensional and are identical at all z, irrespective of the length of the wires. If you're interested in the end-effects of finite length wires, then you should use a finite element field map. [Default: 100\ cm.] 3 density The density of the material in g/cm\³ of which these wires are made. Used by the "-> &OPTIMISE -> 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. This may be a symbolic expression in terms of "-> &CELL -> DEFINE"d variables and you may use the "-> &CELL -> ROWS -> loop-variable" I to construct symbolic expressions. [Default: 19.3\ g/cm\³, i.e. 20\ \μm gold-plated tungsten wire] 3 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 less powerful than the method using the "-> &CELL -> ROWS -> loop-variable" and the increments have therefore been suppressed as of version\ 5. This modification is not backwards compatible - input files prepared for Garfield\ 4 and earlier need to be modified. 3 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 until "-> &CELL -> ROWS -> n"-1 for the last wire. 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 explicitly by means of curly brackets, expressions in terms of "-> &CELL -> DEFINE"d variables and the loop variable are automatically evaluated. Curly brackets should not be used with such variables. 2 SAVE-FIELD-MAP Performs a binary write of the current field map. Files written by this command can be read by the "-> &CELL -> READ-FIELD-MAP" command. This command is executed immediately, unlike the "-> &CELL -> WRITE" command which is only executed when the section is left. The field map must therefore be present (via a "-> &CELL -> 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. In addition, restoring field maps from binary files is usually much faster. However, binary files are not portable between computer systems. Please the original field map files - the format of binary field maps changes whenever new elements are added to the field map. Format: !W
  SAVE-FIELD-MAP   file
!W
Example: See "-> &CELL -> READ-FIELD-MAP" 2 SOLIDS The SOLIDS command adds solid volumes to the chamber. Solids generate the field through an interface with neBEM if potentials, dielectric constants or other boundary conditions have been set for all of them. Otherwise, solids do not affect the field in the chamber, but they can nevertheless be useful for the following reasons: !Wul_start - Solids can serve as start and end point of drift-lines. This is needed to compute the arrival time distributions for electrodes and to determine the collection statistics. - Solids are shown in the drawings, thus making the interpretation of drift-lines easier. - When associated with elements in a field map, solids are used to classify signals as direct or cross induced. !Wul_end Entering these volumes is not mandatory. The drift-line calculation routines for instance, can infer their presence in most cases from the dielectric constants in the field map. If you do not enter any solids in a chambers composed of wires and planes, then all wires are automatically copied to cylindrical solids to ensure the wires are visible in "-> &FIELD -> AREA -> 3D" and "-> &FIELD -> AREA -> CUT" type plots. This copy is not performed if you enter at least 1 solid yourself. 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: !W
  SOLIDS
  {"-> &CELL -> SOLIDS -> BOX" | "-> &CELL -> SOLIDS -> CYLINDER" | "-> &CELL -> SOLIDS -> EXTRUSION" | "-> &CELL -> SOLIDS -> HOLE" | "-> &CELL -> SOLIDS -> RIDGE" | "-> &CELL -> SOLIDS -> SPHERE" | "-> &CELL -> SOLIDS -> WIRE"} parameters
  ...
  (blank line)
!W
Example 1, solids not affecting the field: !W
  "-> &CELL -> 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
        "-> &CELL -> SOLIDS -> hole" "-> &CELL -> SOLIDS -> hole -> centre" {x,y} +0.0110 "-> &CELL -> SOLIDS -> hole -> direction" 0 0 1 ...
           "-> &CELL -> SOLIDS -> hole -> half-lengths" 0.0100 0.0100 0.0010 ...
           upper-"-> &CELL -> SOLIDS -> hole -> radius" 0.0080 lower-"-> &CELL -> SOLIDS -> hole -> radius" 0.0080 ...
           "-> &CELL -> SOLIDS -> hole -> n" = 5 ...
           conductor-3
        "-> &CELL -> SOLIDS -> hole -> centre" {x,y} +0.0050 "-> &CELL -> SOLIDS -> hole -> direction" 0 0 1 ...
           "-> &CELL -> SOLIDS -> hole -> half-lengths" 0.0100 0.0100 0.0050 ...
           upper-"-> &CELL -> SOLIDS -> hole -> radius" 0.0070 lower-"-> &CELL -> SOLIDS -> hole -> radius" 0.0040 ...
           "-> &CELL -> SOLIDS -> hole -> n" = 5 ...
           dielectric
        "-> &CELL -> SOLIDS -> hole -> centre" {x,y} -0.0050 "-> &CELL -> SOLIDS -> hole -> direction" 0 0 1 ...
           "-> &CELL -> SOLIDS -> hole -> half-lengths" 0.0100 0.0100 0.0050 ...
           upper-"-> &CELL -> SOLIDS -> hole -> radius" 0.0040 lower-"-> &CELL -> SOLIDS -> hole -> radius" 0.0070 ...
           "-> &CELL -> SOLIDS -> hole -> n" = 5 ...
           dielectric
        "-> &CELL -> SOLIDS -> hole -> centre" {x,y} -0.0110 "-> &CELL -> SOLIDS -> hole -> direction" 0 0 1 ...
           "-> &CELL -> SOLIDS -> hole -> half-lengths" 0.0100 0.0100 0.0010 ...
           upper-"-> &CELL -> SOLIDS -> hole -> radius" 0.0080 lower-"-> &CELL -> SOLIDS -> hole -> radius" 0.0080 ...
           "-> &CELL -> SOLIDS -> hole -> n" = 5 ...
           conductor-3
     Enddo
  Enddo
!W
This represents an array of 9\ double-tapered cylindrical holes in a copper clad foil of dielectric material, similar to a GEM foil. These solids have no effect on the field. !W

!W Example 2, dielectric materials: !W

  "-> &CELL"
  solids
  "-> &CELL -> SOLIDS -> box"   centre 0 0 -1.2 ...
        half-lengths 5 5 0.2 ...
        conductor-1 ...
        voltage 1
  "-> &CELL -> SOLIDS -> box"   centre 0 0 0 ...
        half-lengths 5 5 1 ...
        dielectricum-1 ...
        epsilon 2
  "-> &CELL -> SOLIDS -> ridge" centre 0 0 1 ...
        half-lengths 2 5 ...
        notch 1 2 ...
        dir 0 0 1 ...
        epsilon 10 ...
        dielectricum-2
  "-> &CELL -> SOLIDS -> box "  centre 0 0 8 ...
        half-lengths 5 5 0.2 ...
        conductor-1 ...
        voltage -1

  "-> &CELL -> nebem" max-elem 2

  "-> &FIELD"
  // View the structure
  "-> &FIELD -> area" -9 -9 -2 9 9 9 ...
      nooutline ...
      light -20 -40 ...
      view -3*x+5*y-1*z=0 3d
  Call "-> Call -> plot_field_area"
  Call "-> Call -> plot_end"
  // Contour plot
  "-> &FIELD -> area" -3 -1 -1  3 5 5 ...
      view y=0 cut rot 180
  "-> &FIELD -> grid" 25
  "-> &FIELD -> plot-field" cont
!W
In this example, the solids define the field through the neBEM interface. The field between 2 conducting plates is distorted by the presence of a triangular piece of dielectric material. !W

!W Example 3, importance of discretisation: !W

  "-> &CELL"
  solids
  "-> &CELL -> SOLIDS -> box"      "-> &CELL -> SOLIDS -> box -> centre" 0 0 0  ...
           "-> &CELL -> SOLIDS -> box -> half-lengths" 5 5 0.1 ...
           "-> &CELL -> SOLIDS -> box -> voltage" 1000 ...
           "-> &CELL -> SOLIDS -> box -> discretisation" 10
  "-> &CELL -> SOLIDS -> box"      "-> &CELL -> SOLIDS -> box -> centre" 0 0 1  ...
           "-> &CELL -> SOLIDS -> box -> half-lengths" 5 5 0.1 ...
           "-> &CELL -> SOLIDS -> box -> voltage" 0 ...
           "-> &CELL -> SOLIDS -> box -> discretisation" 10

  "-> &FIELD"
  area -7 -7 -1 7 7 2 view z=0.89
  pl cont v n=50 range 0 500

  "-> &CELL"
  solids
  "-> &CELL -> SOLIDS -> box"      "-> &CELL -> SOLIDS -> box -> centre" 0 0 0  ...
           "-> &CELL -> SOLIDS -> box -> half-lengths" 5 5 0.1 ...
           "-> &CELL -> SOLIDS -> box -> voltage" 1000 ...
           "-> &CELL -> SOLIDS -> box -> discretisation" 10
  "-> &CELL -> SOLIDS -> box"      "-> &CELL -> SOLIDS -> box -> centre" 0 0 1  ...
           "-> &CELL -> SOLIDS -> box -> half-lengths" 5 5 0.1 ...
           "-> &CELL -> SOLIDS -> box -> voltage" 0 ...
           "-> &CELL -> SOLIDS -> box -> discretisation" 10 bottom-"-> &CELL -> SOLIDS -> box -> discretisation" 1

  "-> &FIELD"
  "-> &FIELD -> area" -7 -7 -1 7 7 2 view z=0.89
  pl cont v n=50 range 0 500
!W
This examples illustrates the impact of the discretisation of a face of a solid. The first plot (left) shows the potential in a capacitor with just 1\ element per plane, while the second plot (right) shows the potential when the plate has been subdivided in 10\×10 elements. Note that the boundary conditions are not strictly respected: in the boundary element approach, the fields are solutions of the Maxwell equations but they only satisfy the boundary conditions at the collocation points. In the finite element approach, the potentials are not solutions of the Maxwell equations, but they strictly respect the boundary conditions. !W

!W Example 4, selective discretisation: !W

  &CELL
  nebem target-element-size 0.1
  solids
  box      centre  0 0 0 half-lengths 1 1 1 voltage 1 ...
           discretisation 0.5
  box      centre  3 0 0 half-lengths 1 2 2 voltage 1 ...
           front-discretisation 0.2 back-discretisation automatic
  cylinder centre 10 0 0 half-length 1 radius 1 voltage -1 ...
           discretisation 0.5 top-discretisation 0.2

  nebem target-element-size 0.8
  opt cell-print
  &MAIN
!W
The default discretisation length is set to 1\ mm in the first NEBEM statement. This value is only used for 4 of the faces of the second box. All faces of the first box and the cylinder initially get a discretisation size of 5\ mm, a value that is overruled for one of the faces of the cylinder. The face of the second, larger, box that is in partial contact with the first, smaller, box is given an AUTOMATIC discretisation length. The part of this face that is in contact will inherit the discretisation of the first box, which has been explicitely specified to be 5\ mm. For other parts of this face a discretisation length of 8\ mm will be used, as set in the second NEBEM statement. 3 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: !W
  BOX  "-> &CELL -> SOLIDS -> BOX -> CENTRE" cx cy cz ...
       "-> &CELL -> SOLIDS -> BOX -> HALF-LENGTHS" lx ly lz ...
       ["-> &CELL -> SOLIDS -> BOX -> DIRECTION" dx dy dz] ...
       ["-> &CELL -> SOLIDS -> BOX -> VOLTAGE" v] ...
       ["-> &CELL -> SOLIDS -> BOX -> FLOATING-CONDUCTOR"] ...
       ["-> &CELL -> SOLIDS -> BOX -> CHARGE" q] ...
       ["-> &CELL -> SOLIDS -> BOX -> EPSILON" eps] ...
       ["-> &CELL -> SOLIDS -> BOX -> material"] ...
       [LABEL "-> &CELL -> SOLIDS -> BOX -> label"]
       [FRONT-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"] ...
       [BACK-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"] ...
       [RIGHT-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"] ...
       [LEFT-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"] ...
       [TOP-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"] ...
       [BOTTOM-DISCRETISATION "-> &CELL -> SOLIDS -> BOX -> discretisation"]
!W
!WIllustration: !W

!W !W

!WA set of boxes that are intersecting each other. !WShown using the default colour density table, with outlining. 4 CENTRE The location of the centre of gravity of the box. [No default.] 4 HALF-LENGTHS Half the overall dimensions of the box. [No default.] 4 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.] 4 CHARGE Charge applied to the surfaces of the box. The charge is added to the surface charges needed to satisfy the boundary conditions. The box can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the box, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The box will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the box relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 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: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 discretisation The approximate linear size of the elements you would like neBEM to use when discretising. Garfield generates, for each solid, a set of flat panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. !W !W

The designation of the surfaces is as follows: !Wul_start - front: the +x face of the box; - back: the -x face of the box; - right: the +y face of the box; - left: the -y face of the box; - top: the +z face of the box; - bottom: the -z face of the box; !Wul_end All references to coordinates concern the situation before the solid is rotated in place. The discretisation length can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 3 CYLINDER Enters a cylinder. For many purposes, cylinders and wires are equivalent, but the differences are important when using neBEM to compute the field: !Wul_start - as a true 3-dimensional cylinder: appropriate if the radius of the cylinder is large compared to either its length or the distance to other electrodes; - as a "-> &CELL -> SOLIDS -> CYLINDER -> wire": the preferred approach if the radius is small compared to the length of the cylinder and to the distance to other electrodes; neBEM applies a thin-wire approximation which is more efficient, under these conditions, and which leads for an equal number of elements, to a more accurate near-field. !Wul_end Mandatory parameters are the location of the centre, the radius and the length. The direction defaults to the z-axis. Format: !W

  CYLINDER  "-> &CELL -> SOLIDS -> CYLINDER -> CENTRE" cx cy cz ...
            RADIUS "-> &CELL -> SOLIDS -> CYLINDER -> radius" ... ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> OUTER-RADIUS" | "-> &CELL -> SOLIDS -> CYLINDER -> MEAN-RADIUS"]
            "-> &CELL -> SOLIDS -> CYLINDER -> HALF-LENGTH" lz ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> DIRECTION" dx dy dz] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> VOLTAGE" v] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> FLOATING-CONDUCTOR"] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> CHARGE" q] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> EPSILON" eps] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> material"] ...
            [LABEL "-> &CELL -> SOLIDS -> CYLINDER -> label"] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> ROTATE" angle] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> N" n] ...
            [TOP-LID-DISCRETISATION "-> &CELL -> SOLIDS -> CYLINDER -> discretisation"] ...
            [BODY-DISCRETISATION "-> &CELL -> SOLIDS -> CYLINDER -> discretisation"] ...
            [BOTTOM-LID-DISCRETISATION "-> &CELL -> SOLIDS -> CYLINDER -> discretisation"] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> TOP-LID" | NOTOP-LID] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> BOTTOM-LID" | NOBOTTOM-LID] ...
            ["-> &CELL -> SOLIDS -> CYLINDER -> LIDS" | NOLIDS]
!W
!WIllustration: !W

!W !W

!WA set of cylinders, partially hiding each other. !WEach cylinder is drawn with 50 panels, and 20 colour shades are used. 4 CENTRE The location of the centre of gravity of the cylinder. [No default.] 4 radius The radius of the cylinder. The decision whether a particle is inside or outside the cylinder, is made assuming a genuine cylinder. For plotting and neBEM field calculations however, a polygonal approximation is made and the precise interpretation of the radius is influenced by the "-> &CELL -> SOLIDS -> CYLINDER -> MEAN-RADIUS" and "-> &CELL -> SOLIDS -> CYLINDER -> OUTER-RADIUS" options. [No default.] 4 OUTER-RADIUS By default, the polygon is inscribed in a circle of the specified "-> &CELL -> SOLIDS -> CYLINDER -> radius". 4 MEAN-RADIUS If this option is specified, then the "-> &CELL -> SOLIDS -> CYLINDER -> radius" will be interpreted as the average radius of the polygon that approximates the cylinder. The radius at the vertices will be larger than the smallest enveloping circle by a factor: !W

  2/(1 + arcsinh(tan(\α) cos(\α) / tan(\α)))
!W
where !W
  \α = 1/4 \π / ("-> &CELL -> SOLIDS -> CYLINDER -> N"-1)
!W
If you place a precisely fitting hole around the cylinder, then you should use the same option for the hole. [This is not default.] 4 HALF-LENGTH Half the overall length of the cylinder, as measured along the central axis. [No default.] 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.] 4 CHARGE Charge applied to the surfaces of the cylinder. The charge is added to the surface charges needed to satisfy the boundary conditions. The cylinder can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the cylinder, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The cylinder will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the cylinder relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 4 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: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 N The cylinder is drawn as a polygon with a finite number of panels. The number of corners of the polygon equals 4(n-1). Thus, n=2 will produce a square, n=3 an octagon etc. The interpretation of n is the same for holes and cylinders. Cylinders with a given n will precisely fit in holes with the same n, provided the radii and axes match. Drift line termination assumes a perfect cylinder, the choice of n therefore has no importance for this purpose. However, the number of surface panels passed on to neBEM field calculations rises with n and the visual quality of 3D views improves with n. [By default, N is chosen in function of the size occupied by the cylinder in the drawing. N must be larger than 1.] 4 WIRE Requests the use of the thin-wire approximation. This is equivalent to entering a "-> &CELL -> SOLIDS -> WIRE". [This is not default and mutually exclusive with specifying "-> &CELL -> SOLIDS -> CYLINDER -> N".] 4 ROTATE Specifies a rotation angle of the cylinder in degrees. Such a rotation is meaningful only if "-> &CELL -> SOLIDS -> CYLINDER -> N" has been chosen small. Rotations have only an optical effect. 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: -\π/4\ radian] 4 discretisation The approximate linear size of the elements you would like neBEM to use when discretising. Garfield generates, for each solid, a set of panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. !W !W

The designation of the surfaces is as follows: !Wul_start - top: the circular area at +z; - body: the outside of the cylindrical part, the only discretisation length which is used for "-> &CELL -> SOLIDS -> CYLINDER -> wire"s. - bottom: the circular area at -z. !Wul_end All references to coordinates concern the situation before the solid is rotated in place. The discretisation lengths can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 4 TOP-LID Requests the cylinder be closed with a (polygonal) lid at +z. Not closing the cylinder results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the cylinders open is therefore recommendable practice for periodic chambers. The cylinder will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type cylinders. [This is default.] 4 BOTTOM-LID Requests the cylinder be closed with a (polygonal) lid at -z. Not closing the cylinder results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the cylinders open is therefore recommendable practice for periodic chambers. The cylinder will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type cylinders. [This is default.] 4 LIDS Requests the cylinder be closed with a (polygonal) lid at both ends. Not closing the cylinder results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the cylinders open is therefore recommendable practice for periodic chambers. The cylinder will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type cylinders. [This is default.] 3 EXTRUSION Enters an extrusion. Mandatory parameters are the extrusion profile and the half-length. The direction defaults to the z-axis and the central position to (0,0,0). Format: !W

  EXTRUSION  "-> &CELL -> SOLIDS -> EXTRUSION -> CENTRE" cx cy cz ...
             "-> &CELL -> SOLIDS -> EXTRUSION -> HALF-LENGTH" lz ...
             "-> &CELL -> SOLIDS -> EXTRUSION -> PROFILE" x1 y1  x2 y2  x3 y3 ... xn yn ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> DIRECTION" dx dy dz] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> VOLTAGE" v] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> FLOATING-CONDUCTOR"] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> CHARGE" q] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> EPSILON" eps] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> material"] ...
             [LABEL "-> &CELL -> SOLIDS -> EXTRUSION -> label"] ...
             [TOP-LID-DISCRETISATION "-> &CELL -> SOLIDS -> EXTRUSION -> discretisation"] ...
             [BODY-DISCRETISATION "-> &CELL -> SOLIDS -> EXTRUSION -> discretisation"] ...
             [BOTTOM-LID-DISCRETISATION "-> &CELL -> SOLIDS -> EXTRUSION -> discretisation"] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> TOP-LID" | NOTOP-LID] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> BOTTOM-LID" | NOBOTTOM-LID] ...
             ["-> &CELL -> SOLIDS -> EXTRUSION -> LIDS" | NOLIDS]
!W
!WIllustration: !W

!W !W

!WAn extrusion !W

  "-> &CELL"
  "-> &CELL -> nebem" "-> &CELL -> nebem -> target-element-size" 1
  "-> &CELL -> solids"
  "-> &CELL -> solids -> box" centre        0   0  10 ...
      half-lengths 10  10   0 ...
      volt          0
  "-> &CELL -> solids -> box" centre        0   0 -10 ...
      half-lengths 10  10   0 ...
      volt          0
  extrusion centre  0  0  0 ...
      half-length   4 ...
      profile       -5 -1   -2 -5   -2 -2  -3 -2   0 0    2 -2    3 4 ...
      voltage       1

  opt "-> &CELL -> OPTIONS -> cell-print"
  "-> &FIELD"
  "-> &FIELD -> area" -6 -6 -6 6 6 6 view x+2*y-3*z=0 "-> &FIELD -> AREA -> nebem"
  Call "-> Call -> plot_field_area"
  Call "-> Call -> plot_end"
!W
4 CENTRE The location to where the reference point (0,0) of the extrusion profile should be moved. [By default, (0,0,0).] 4 HALF-LENGTH Half the overall length of the extrusion, as measured along the central axis. [No default.] 4 DIRECTION The direction vector of the central axis of the extrusion. 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.] 4 CHARGE Charge applied to the surfaces of the extrusion. The charge is added to the surface charges needed to satisfy the boundary conditions. The extrusion can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the extrusion, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The extrusion will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the extrusion relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 4 material Specifies whether the extrusion is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 PROFILE The profile of the extrusion is entered by means of a series of (x,y) coordinates. [Ny default, mandatory parameter.] 4 discretisation The approximate linear size of the elements you would like neBEM to use when discretising. Garfield generates, for each solid, a set of panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. !W !W

The designation of the surfaces is as follows: !Wul_start - top: the profile at +z; - body: the outside of the extruded part; - bottom: the profile at -z. !Wul_end All references to coordinates concern the situation before the solid is rotated in place. The discretisation lengths can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 4 TOP-LID Requests the extrusion be closed with a (polygonal) lid at +z. Not closing the extrusion results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the extrusions open is therefore recommendable practice for periodic chambers. The extrusion will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type extrusions. [This is default.] 4 BOTTOM-LID Requests the extrusion be closed with a (polygonal) lid at -z. Not closing the extrusion results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the extrusions open is therefore recommendable practice for periodic chambers. The extrusion will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type extrusions. [This is default.] 4 LIDS Requests the extrusion be closed with a (polygonal) lid at both ends. Not closing the extrusion results in smaller, more efficient neBEM models since polygonal lids are subdivided in a potentially large number of triangular elements, which are computationally less efficient. Leaving the extrusions open is therefore recommendable practice for periodic chambers. The extrusion will appear closed for all visualisation techniques, except "-> &FIELD -> AREA -> NEBEM". This option has no effect on wire-type extrusions. [This is default.] 3 HOLE Enters an, optionally tapered, cylindrical 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: !W

  HOLE  "-> &CELL -> SOLIDS -> HOLE -> CENTRE" cx cy cz ...
        RADIUS "-> &CELL -> SOLIDS -> HOLE -> radius" | UPPER-RADIUS r_up LOWER-RADIUS r_low ...
        ["-> &CELL -> SOLIDS -> HOLE -> OUTER-RADII" | "-> &CELL -> SOLIDS -> HOLE -> MEAN-RADII"]
        "-> &CELL -> SOLIDS -> HOLE -> HALF-LENGTHS" lx ly lz ...
        ["-> &CELL -> SOLIDS -> HOLE -> DIRECTION" dx dy dz] ...
        ["-> &CELL -> SOLIDS -> HOLE -> VOLTAGE" v] ...
        ["-> &CELL -> SOLIDS -> HOLE -> FLOATING-CONDUCTOR"] ...
        ["-> &CELL -> SOLIDS -> HOLE -> CHARGE" q] ...
        ["-> &CELL -> SOLIDS -> HOLE -> EPSILON" eps] ...
        ["-> &CELL -> SOLIDS -> HOLE -> material"] ...
        [LABEL "-> &CELL -> SOLIDS -> HOLE -> label"] ...
        ["-> &CELL -> SOLIDS -> HOLE -> N" n]
        [FRONT-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [BACK-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [RIGHT-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [LEFT-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [TOP-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [BOTTOM-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"] ...
        [CYLINDER-DISCRETISATION "-> &CELL -> SOLIDS -> HOLE -> discretisation"]
!W
!WIllustration: !W

!W !W

!WTwo holes, on the left with N=2, on the right with N=20. !WBoth are drawn with outlining. 4 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.] 4 radius 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. The decision whether a particle is inside or outside the cylindric part of the hole is made assuming a genuine cylinder. For plotting and neBEM field calculations however, a polygonal approximation is made and the precise interpretation of the radius is influenced by the "-> &CELL -> SOLIDS -> HOLE -> MEAN-RADII" and "-> &CELL -> SOLIDS -> HOLE -> OUTER-RADII" options. [No default.] 4 OUTER-RADII By default, the polygonal hole is inscribed in a circle of the specified "-> &CELL -> SOLIDS -> HOLE -> radius". 4 MEAN-RADII If this option is specified, then the "-> &CELL -> SOLIDS -> HOLE -> radius" will be interpreted as the average radius of the polygon that approximates the cylinder. The radius at the vertices will be larger than the smallest enveloping circle by a factor: !W

  2/(1 + arcsinh(tan(\α) cos(\α) / tan(\α)))
!W
where !W
  \α = 1/4 \π / ("-> &CELL -> SOLIDS -> HOLE -> N"-1)
!W
If you insert a precisely fitting cylinder in the hole, then you should use the same option for the cylinder. [This is not default.] 4 HALF-LENGTHS Half the overall dimensions of the box. [No default.] 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.] 4 CHARGE Charge applied to the surfaces of the hole. The charge is added to the surface charges needed to satisfy the boundary conditions. The hole can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the hole, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The hole will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the hole relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 4 material Specifies whether the hole is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 N The hole is drawn as an outer box and an inner hollow cylinder. The choice of n has no impact on the box. The inner cylinder is drawn as a polygon with a finite number of panels. The number of corners of this polygon equals 4(n-1). Thus, n=2 will produce a square, n=3 an octagon. The interpretation of n is the same for holes and cylinders. Cylinders with a given n will precisely fit in holes with the same n, provided the radii and axes match. Drift line termination assumes a perfect cylinder, the choice of n therefore has no importance for this purpose. However, the number of surface panels passed on to neBEM field calculations rises with n and the visual quality of 3D views improves with n. [By default, N is chosen in function of the size occupied by the cylinder in the drawing. N must be larger than 1.] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 discretisation The approximate linear size of the elements you would like neBEM to use when discretising. Garfield generates, for each solid, a set of panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. !W !W

The designation of the surfaces is as follows: !Wul_start - front: the +x face of the box; - back: the -x face of the box; - right: the +y face of the box; - left: the -y face of the box; - top: the +z face of the box; - bottom: the -z face of the box; - hole or cylinder: the surface of the hole. !Wul_end All references to coordinates concern the situation before the solid is rotated in place. The discretisation lengths can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 3 RIDGE Enters a ridge, similar to a Toblerone bar. Mandatory parameters are the location of the centre and size of the floor, and the position of the ridge proper (the highest part of a roof). The ridge proper is by default aligned with the y-axis, the (x,y) plane is taken to the floor of the construction. Format: !W

  RIDGE  "-> &CELL -> SOLIDS -> RIDGE -> CENTRE" cx cy cz ...
         "-> &CELL -> SOLIDS -> RIDGE -> HALF-LENGTHS" lx ly ...
         "-> &CELL -> SOLIDS -> RIDGE -> NOTCH" rx rz ...
         ["-> &CELL -> SOLIDS -> RIDGE -> DIRECTION" dx dy dz] ...
         ["-> &CELL -> SOLIDS -> RIDGE -> VOLTAGE" v] ...
         ["-> &CELL -> SOLIDS -> RIDGE -> FLOATING-CONDUCTOR"] ...
         ["-> &CELL -> SOLIDS -> RIDGE -> CHARGE" q] ...
         ["-> &CELL -> SOLIDS -> RIDGE -> EPSILON" eps] ...
         ["-> &CELL -> SOLIDS -> RIDGE -> material"] ...
         [LABEL "-> &CELL -> SOLIDS -> RIDGE -> label"]
         [FRONT-DISCRETISATION "-> &CELL -> SOLIDS -> RIDGE -> discretisation"] ...
         [BACK-DISCRETISATION "-> &CELL -> SOLIDS -> RIDGE -> discretisation"] ...
         [RIGHT-DISCRETISATION "-> &CELL -> SOLIDS -> RIDGE -> discretisation"] ...
         [LEFT-DISCRETISATION "-> &CELL -> SOLIDS -> RIDGE -> discretisation"] ...
         [FLOOR-DISCRETISATION "-> &CELL -> SOLIDS -> RIDGE -> discretisation"]
!W
!W !WIllustration: !W

!W !W

!WA ridge (blue) used to model a surface irregularity of a !Wdielectric medium (yellow) between conductors (green). 4 CENTRE The centre of the floor of the ridge in the (x,y) plane at z=0. [No default.] 4 HALF-LENGTHS Half the overall dimensions of the floor. [No default.] 4 NOTCH Takes 2 arguments: the offset in the x-direction of the ridge and the height of the ridge measured from the floor. If the offset is set to 0, then the ridge will be symmetric. This parameter is mandatory and is by default set to 0. The height must be specified and must be positive (non-zero). 4 DIRECTION A direction vector that specifies the orientation of the z-axis of the box in space. The ridge proper is taken to be parallel with the y-axis. 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.] 4 CHARGE Charge applied to the surfaces of the box. The charge is added to the surface charges needed to satisfy the boundary conditions. The box can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the box, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The box will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the box relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 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: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 discretisation The approximate linear size of the elements you would like neBEM to use when discretising. Garfield generates, for each solid, a set of panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. !W !W

The designation of the surfaces is as follows: !Wul_start - front: the inclined rectangular face that looks towards +x; - back: the inclined rectangular face that looks towards -x; - right: the +y triangular face of the ridge; - left: the -y triangular face of the ridge; - floor: the z=0 floor of the ridge. !Wul_end All references to coordinates concern the situation before the solid is rotated in place. The discretisation lengths can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 3 SPHERE Enters a sphere. Mandatory parameters are the location of the centre and the dimensions. The direction defaults to the z-axis. Format: !W

  SPHERE  "-> &CELL -> SOLIDS -> SPHERE -> CENTRE" cx cy cz ...
          "-> &CELL -> SOLIDS -> SPHERE -> RADIUS" r ...
          ["-> &CELL -> SOLIDS -> SPHERE -> VOLTAGE" v] ...
          ["-> &CELL -> SOLIDS -> SPHERE -> FLOATING-CONDUCTOR"] ...
          ["-> &CELL -> SOLIDS -> SPHERE -> CHARGE" q] ...
          ["-> &CELL -> SOLIDS -> SPHERE -> EPSILON" eps] ...
          ["-> &CELL -> SOLIDS -> SPHERE -> material"] ...
          [LABEL "-> &CELL -> SOLIDS -> SPHERE -> label"] ...
          ["-> &CELL -> SOLIDS -> SPHERE -> N" n]
          [DISCRETISATION "-> &CELL -> SOLIDS -> SPHERE -> discretisation"] ...
!W
!WIllustration: !W

!W !W

!WA sphere with 50 by 50 panels, shown with a colour table of 50 elements. 4 CENTRE The location of the centre of gravity of the sphere. [No default.] 4 RADIUS The radius of the sphere. [No default.] 4 CHARGE Charge applied to the surfaces of the sphere. The charge is added to the surface charges needed to satisfy the boundary conditions. The sphere can either be a dielectric or a conductor. In the process of being implemented - initially, the charge is equally distributed over all surfaces, selection of surface panels is planned to be added later. Specifying this option implies the use of neBEM to solve the field. 4 VOLTAGE Voltage of the sphere, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The sphere will assume a uniform voltage common on all its surface panels. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 EPSILON Dielectric constant of the sphere relative to vacuum. Specifying this option implies the use of neBEM to solve the field. 4 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: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - DIELECTRICUM "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" Equivalent to DIELECTRICUM-1 DIELECTRICUM-1 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1" - DIELECTRICUM-2 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" - DIELECTRICUM-3 "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 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. N must be equal to, or larger than, 3. [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 that setting will be used no matter how large or small the sphere appears in the drawing.] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 discretisation The approximate linear size of the elements you would like neBEM to use. Garfield generates, for each solid, a set of panels that together cover the faces. These panels, arbitrary convex polygons, are sub-divided when isolating contact areas between solids and also in order to comply with the neBEM requirement that it be given only rectangles and right-angled triangles. The triangles and rectangles handed to neBEM are called "primitives". For reasons of accuracy neBEM as a rule sub-divides the primitives into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user. In neBEM, the level of discretisation requested is described by 2 integers: the number of elements that is to be generated along each of 2 sides adjacent to a right angle. Since the shape, orientation and size of the primitives are non-trivial to predict, the level of discretisation is specified on the Garfield side as the desired length of the sides of the elements. All panels covering the sphere are subject to the same discretisation. The discretisation lengths can be set in several ways, see Example\ 4 for the "-> &CELL -> SOLIDS" command: !Wul_start - by setting a default discretisation length to be used for all solids, by means of the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" keyword of a "-> &CELL -> NEBEM" command issued before the SOLIDS command; - collectively for all faces of a single solid, e.g. DISCRETISATION=0.1, this overrides the default used for all solids; - individually for one or more faces of the solid, e.g. TOP-DISCRETISATION=0.2, this overrides any previous collective setting; - by setting the discretisation length of a face to AUTOMATIC; if this face is in partial contact, then the discretisation length of the other face will be used, if it has been set; if not, and also in the absence of contact, the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when leaving the cell section. !Wul_end Discretisation lengths have to be given in cm. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 3 WIRE Enters a wire solid. These are to be used if the cell contains wires that are non-parallel or short compared to their length. If the cell can be described in terms "-> &CELL -> rows" of long and parallel wires, "-> &CELL -> plane"s, a "-> &CELL -> tube" and "-> &CELL -> periodicity", then it is preferable to do so. Wire solids are treated as cylinders for most purposes, but neBEM handles them as charges distributed along the axis in such a manner that the surface is at the specified potential. This is equivalent to the thin-wire approximation used for wire and plane cells. This approach makes more efficient use of the elements than a solid cylinder in case the radius of the cylinder is small compared to its length and to the distance to other electrodes. A "-> &CELL -> SOLIDS -> CYLINDER" should be used if these conditions are not fulfilled. Wires are always conductors. Mandatory parameters are the location of the centre, the radius and the length. The direction defaults to the z-axis. Format: !W

  WIRE  "-> &CELL -> SOLIDS -> WIRE -> CENTRE" cx cy cz ...
        "-> &CELL -> SOLIDS -> WIRE -> RADIUS" r ...
        "-> &CELL -> SOLIDS -> WIRE -> HALF-LENGTH" lz ...
        ["-> &CELL -> SOLIDS -> WIRE -> DIRECTION" dx dy dz] ...
        ["-> &CELL -> SOLIDS -> WIRE -> VOLTAGE" v] ...
        ["-> &CELL -> SOLIDS -> WIRE -> FLOATING-CONDUCTOR"] ...
        ["-> &CELL -> SOLIDS -> WIRE -> material"] ...
        [LABEL "-> &CELL -> SOLIDS -> WIRE -> label"] ...
        [DISCRETISATION "-> &CELL -> SOLIDS -> WIRE -> discretisation"]
!W
Example: Two perpendicular wires cross each other at a distance of 1\ mm. !W
  "-> &CELL"
  "-> &CELL -> nebem" "-> &CELL -> NEBEM -> target-element-size" 0.01 "-> &CELL -> NEBEM -> maximum-elements" 100
  "-> &CELL -> solids"
  wire "-> &CELL -> SOLIDS -> WIRE -> centre"      0      0   -0.05 ...
       "-> &CELL -> SOLIDS -> WIRE -> half-length" 1 ...
       "-> &CELL -> SOLIDS -> WIRE -> radius"      0.0100 ...
       "-> &CELL -> SOLIDS -> WIRE -> direction"   1      0    0 ...
       "-> &CELL -> SOLIDS -> WIRE -> voltage"    -1
  wire "-> &CELL -> SOLIDS -> WIRE -> centre"      0      0   +0.05 ...
       "-> &CELL -> SOLIDS -> WIRE -> half-length" 1 ...
       "-> &CELL -> SOLIDS -> WIRE -> radius"      0.0100 ...
       "-> &CELL -> SOLIDS -> WIRE -> direction"   0      1    0 ...
       "-> &CELL -> SOLIDS -> WIRE -> voltage"    +1

  "-> &FIELD"
  "-> &FIELD -> area" -0.25 -0.25 -0.25 0.25 0.25 0.25 view z=0
  "-> &FIELD -> grid" 50
  "-> &FIELD -> plot-field" "-> &FIELD -> PLOT-FIELD -> surface" e

  "-> &FIELD -> area" -1.2 -1.2 -1.2 1.2 1.2 1.2 view z=0
  "-> &FIELD -> plot-field" "-> &FIELD -> PLOT-FIELD -> surface" e

  "-> &FIELD -> track" -1 0.010001 -0.05   1 0.010001 -0.05
  "-> &FIELD -> plot-field" "-> &FIELD -> PLOT-FIELD -> graph" v range -1.01 -0.99

!W
The first plot (reproduced below), like the second, shows how the field increases in the area where the wires are nearest to each other. The third plot verifies the boundary condition. !W 4 CENTRE The location of the centre of gravity of the wire. [No default.] 4 RADIUS The radius of the wire. [No default.] 4 HALF-LENGTH Half the overall length of the wire. [No default.] 4 DIRECTION The direction vector of the wire. 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.] 4 VOLTAGE Voltage of the wire, which is assumed to be conducting. Specifying this option implies the use of neBEM to solve the field. 4 FLOATING-CONDUCTOR The wire will assume a uniform voltage on its surface. In the process of being implemented. Specifying this option implies the use of neBEM to solve the field. 4 material Specifies which conductor the wire is made of. To differentiate the solids in drawings, one has the option to choose between various representations: !Wtable_start !T+P +P + . ------------------------------------------------------------------------------------------------------ Type Representation Notes ------------------------------------------------------------------------------------------------------ CONDUCTOR "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" Equivalent to CONDUCTOR-1 CONDUCTOR-1 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1" - CONDUCTOR-2 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" - CONDUCTOR-3 "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" - ------------------------------------------------------------------------------------------------------ !Wtable_end [Default: CONDUCTOR] 4 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 isochrons are drawn etc. [By default, no label is assigned.] 4 discretisation The approximate linear size of the elements you would like neBEM to use. Garfield generates for each wire a single primitive: the centre line of the wire. neBEM sub-divides this primitive into "elements", in a process called "discretisation". The sub-divisions of the primitives are called "elements". Discretisation will perhaps eventually be automated, but for the time being this remains the responsability of the user who has to indicate the length of the desired elements. The discretisation length has to be given in cm. Also the value AUTOMATIC is allowed, in which case the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" will be used that is in effect when the cell section is being left. [Default: the "-> &CELL -> NEBEM -> TARGET-ELEMENT-SIZE" that is in effect at the time the solids are read.] 2 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. With "-> &CELL -> methods -> coordinate_system -> Tube" coordinates, you enter the wire location in Cartesian coordinates which you can combine with a \φ periodicity in degrees. Periodicities in x or y are not permitted, nor are planes in any direction. The potential function for a square tube is expensive to compute compared to the equivalent potential which is used for a cell that has 2 planes at constant x and 2 planes at constant y. Format: !W
  TUBE  ["-> &CELL -> TUBE -> RADIUS" r] ...
        ["-> &CELL -> TUBE -> VOLTAGE" v] ...
        ["-> &CELL -> TUBE -> EDGES" n] ...
        [LABEL "-> &CELL -> TUBE -> label"] ...
        [{PHI-STRIP | Z-STRIP} "-> &CELL -> TUBE -> strip_min" "-> &CELL -> TUBE -> strip_max" ...
           [GAP "-> &CELL -> TUBE -> gap"] [LABEL "-> &CELL -> TUBE -> strip_label"]]
!W
Examples: !W
  tube r=2, v=2000
  tube hexagonal r=5
!W
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 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 VOLTAGE The potential of the tube. [By default 0\ V.] 3 EDGES The number of edges, according to the following table: !Wtable_start !T+ R +P . ------------------------------------------------------------ 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 ------------------------------------------------------------ !Wtable_end Polygons with a larger number of edges can be made available on request. 3 label Serves to identify the tube to "-> &FIELD -> 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.] 3 STRIP Anticipates read-out of a part of the tube. Two kinds of sub-divisions are permitted: radial sectors and slices along the z-axis. 3 strip_min Indicates the starting point of the strip. The location should be indicated in degrees for radial sectors and in cm for slices in z. [Mandatory parameter, no default provided.] 3 strip_max Indicates the end point of the strip. The location should be indicated in degrees for radial sectors and in cm for slices in z. [Mandatory parameter, no default provided.] 3 strip_label A label by which the strip can be referenced in "-> &FIELD -> SELECT" statements, when computing signals induced in the strip 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 strip are only computed if the strip can be selected, and this can only be done if the strip has a label. [By default, no label is assigned to a strip.] 3 gap Indicates the gap width to be used when computing the weighting field for the strip. The gap is specified in cm for z-slices and in degrees for \φ-sectors. [By default, this is taken to be the distance to the central wire, if there is one.] 3 representations The tube will be displayed using the "-> graphics -> REPRESENTATION -> item -> TUBE" representation. Strips, if any, are shown with the "-> graphics -> REPRESENTATION -> item -> STRIPS" representation. 2 WINDOW The window command lets you eliminate elements (triangles, tetrahedra, hexahedra and degenerated hexahedra) of which one or more nodes are located outside a rectangular box. This command has effect only if issued after a "-> &CELL -> FIELD-MAP" or "-> &CELL -> READ-FIELD-MAP" command. Formats for 2D and 3D field maps respectively: !W
  WINDOW xmin ymin xmax ymax
  WINDOW xmin ymin zmin xmax ymax zmax
!W
Example: !W
  "-> &CELL"
  "-> Global" bin `gabriele.bin`
  If "-> algebra -> functions -> exist"(bin) Then
     "-> &CELL -> read-field-map" {bin}
  Else
     "-> &CELL -> field-map" files "e.reg" "v.reg" keep-background maxwell-11 ...
        x-mirror-periodic y-mirror-periodic
     "-> &CELL -> save-field-map" {bin}
  Endif
  window -0.0070 -0.0035 -10 0.0070 0.0035 10
  opt "-> &CELL -> OPTIONS -> cell-print"
!W
2 WRITE Writes a compact format cell dataset that can be retrieved using "-> &CELL -> GET". Although written in plain text, this kind of dataset is not meant to be human-readable. Use the "-> &CELL -> OPTIONS -> LAYOUT" option to visualise a cell and "-> &CELL -> OPTIONS -> CELL-PRINT" to obtain a table of the wire locations, charges etc. Compact format cells should not be edited. The format is chosen to enable a fast restore of wire data. This is useful for chambers which contain large numbers of wires (several 1000s). Otherwise, the overhead is not worth the loss in flexibility. The capacitance matrix is not stored in compact format cell datasets. Field maps are, because of their large size, not saved by the WRITE statement. If reading them with the "-> &CELL -> FIELD-MAP" command takes too much time, and if the size of the full field maps is a point of concern, then consider using "-> &CELL -> SAVE-FIELD-MAP" and "-> &CELL -> READ-FIELD-MAP", which perform a binary (i.e. non-portable) save and retrieve. 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. Format: !W
  WRITE DATASET "-> &CELL -> WRITE -> file" ["-> &CELL -> WRITE -> member"] [REMARK "-> &CELL -> WRITE -> remark"]
!W
Examples: !W
  WR DATA cell.dat cell1 REM "Some cell"
  WR cell.dat cell1 "Some cell"
!W
(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 file The name of the "-> dataset -> structure -> file" in which you wish to write the cell description. 3 member The name by which you will want to reference the "-> dataset -> structure -> member" when retrieving it. 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. The field is left blank by default. 1 &MAGNETIC A magnetic field, if present, can be set in two ways: !Wul_start - by using the "-> &MAGNETIC -> COMPONENTS" command in this section, you can set a parametrised magnetic field as well as a constant field with arbitrary orientation, optionally distorted by the difference in permeability between the wire material and the gas; - by means of the "-> &CELL -> FIELD-MAP" command in the "-> &CELL" section, you can enter a magnetic field map computed by a finite element program. !Wul_end You may use the COMPONENTS command to set a constant magnetic field for use together with an electric field map, but you can not have a magnetic field map for use with an electric field generated by wires and planes. The cell and gas descriptions are not touched when you enter a magnetic field, but commands like "-> &GAS -> MAGBOLTZ" will try and calculate a sensible default B-field range and range of E-B angles if a magnetic field is entered beforehand. [Initially, the magnetic field is off.] 2 COMPONENTS Sets the components of the magnetic field. The radial and angular components of the magnetic field must be zero if your cell has been entered in polar coordinates. Only the z component may be non-zero in this case. Format: !W
  COMPONENTS  {"-> &MAGNETIC -> COMPONENTS -> value"_Bx | "-> &MAGNETIC -> COMPONENTS -> vector"_Bx VS {X|Y|Z} = vector_x | "-> &MAGNETIC -> COMPONENTS -> formula"_Bx} ...
              {value_By | vector_By VS {X|Y|Z} = vector_y | formula_By} ...
              {value_Bz | vector_Bz VS {X|Y|Z} = vector_z | formula_Bz} ...
              [GAUSS | OERSTED | TESLA | V.MICROSEC/CM2]
!W
Examples: !W
  comp 0 0 5000 G
!W
A constant magnetic field of 5000\ G, or 0.5\ T, along the z-axis. !W
  comp -y x 0
!W
A toroidal field specified with 2\ formulae and 1\ constant value. 3 value Use this format if you have one or more constant magnetic field components. If this format is used for all 3\ components of the magnetic field, then the "-> &MAGNETIC -> PERMEABILITY" is taken into account. The magnetic field component should have the form of a "-> algebra -> variables -> types -> Number". 3 vector Format to be used if you have a tabulated form of your magnetic field. If this format is used for 1 or more components of the magnetic field, then the "-> &MAGNETIC -> PERMEABILITY" is not taken into account. Both the field vector and the coordinate vector have to be in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". These 2\ vectors must have the same length. When you issue the COMPONENTS command, a copy of the vectors is made. You may therefore change the vectors afterwards - changes to the vectors do not, however, affect the magnetic field. 3 formula To be used if you know an analytic expression for the magnetic field. If this format is used for 1 or more components of the magnetic field, then the "-> &MAGNETIC -> PERMEABILITY" is not taken into account. Components of the magnetic field that use this format should have the form of a "-> algebra -> variables -> types -> String" which uses the variables X, Y and Z when Cartesian coordinates are used, and R, PHI and Z when the cell is described in polar coordinates. 3 units Garfield internally expressed magnetic fields in a unit that fits in its overall unit system, namely V.\μsec/cm\². This unit is equivalent to 100\ G or 0.01\ T. You have to express all components in the same unit, even if you use different formats. You have to use this unit in calls to the various procedures which take magnetic fields as arguments, such as "-> Call -> MAGNETIC_FIELD" or "-> Call -> DRIFT_VELOCITY". The default unit for the COMPONENTS statement is the Tesla, if you wish to use other units, then you have to specify this. 2 OPTIONS There are no local options in this section, but the options of the top-level "-> OPTIONS" command are accessible. 2 PERMEABILITY Sets the permeability 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 permeabilities are equal. The permeability is taken into account only in case all 3 "-> &MAGNETIC -> COMPONENTS" of the magnetic field have been entered as a constant "-> &MAGNETIC -> COMPONENTS -> value". Format: !W
  PERMEABILITY perm_wire perm_gas
!W
Example: !W
  PERM 1 0
!W
1 &GAS Enters the gas section. This section establishes the gas mixture to be used when drifting electrons and ions. The main quantities that are needed for such calculations are the electron and ion transport properties, as well as the cluster size distribution and the cluster spacing. Some of these properties can be computed: the Magboltz program will calculate the electron drift velocity, diffusion, Townsend and attachment coefficient for nearly arbitrary gas mixtures. The Heed program takes care of clustering, also for nearly arbitrary gas mixtures. If you have measured gas properties, or have access to measurements you trust, you can enter this data in the form of tables. One can also replace parts of the Magboltz tables with measurements. For rapid studies which do not require great accuracy, descriptions of a few common gas mixtures are built in to the program. All existing gas information is cleared by entering the gas section. Format: !W
  &GAS
!W
2 overview The set of useful instructions in the gas section depends of the origin of the gas data: !Wul_start - gas mixture prepared during the run - fully user specified gas mixture - built-in gas mixtures with fixed proportions - retrieval of a gas description previously stored !Wul_end A couple of instructions can be used regardless of the origin. Gas mixture prepared during the run: !Wtable_start !T+IP + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end User specified gas mixture: !Wtable_start !T+IP + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end Historically, Garfield contains a number of experiment-based gas tables. They remain available for backwards compatibility, but their use is not recommended for new applications: !Wtable_start !T+P + . ---------------------------------------------------------------------------------------------------- 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\ %, CH\4\ 20\ %, propanol 7\ % CO2 Loads data for almost pure CO\2\ CO2-80-ETHANE-20 Loads the mixture CO\2\ 80\ %, ethane 20\ % CO2-90-ETHANE-10 Loads the mixture CO\2\ 90\ %, ethane 10\ % CO2-90-ISOBUTANE-10 Loads the mixture CO\2\ 90\ %, isobutane 10\ % ETHANE Loads data for pure ethane ISOBUTANE Loads data for pure isobutane METHANE Loads data for pure methane ---------------------------------------------------------------------------------------------------- !Wtable_end Retrieval of a gas description previously stored: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ GET Retrieves gas data from a dataset ------------------------------------------------------------------------ !Wtable_end General purpose instructions: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ OPTIONS Plotting and printing of the gas tables PLOT-OPTIONS Selects plots, sets ranges and log/lin axes ------------------------------------------------------------------------ !Wtable_end 2 methods 3 coordinate_system The transport properties use the Magboltz 2 coordinate system in which the axes are as follows: !Wul_start - E, the electric field - Btrans: component of B transverse to E, provided B is neither 0 nor parallel with E, otherwise any axis perpendicular to E - E\×B provided B is neither 0 nor parallel with E, otherwise the axis perpendicular to the axes mentioned before !Wul_end The longitudinal diffusion is measured along E, not along the drift velocity vector. The transverse diffusion is the average of the diffusion coefficients along the 2 remaining axes. 2 built_in A set of gas mixtures ready for use, supplied by users of the program, usually based on private or published measurements. These descriptions are often only partial (e.g. no ionisation data, no ion mobilities or no Townsend coefficients). They are provided for backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Example: !W
  ARG-50-ETH-50
!W
(Until further notice, the program will use 50\ % argon, 50\ % ethane.) 3 ARGON-20-ETHANE-80 Loads a mixture of 20\ % argon and 80\ & ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. 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). 3 ARGON-50-ETHANE-50 A mixture of 50\ % argon with 50\ % ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Supplied by Manfred Guckes (transport properties) and Giorgio Sartori and Michela Giavedoni (Padova, parameters part). 3 ARGON-80-ETHANE-20 A mixture of 80\ % argon with 20\ % ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. 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) 3 ARGON-73-METHANE-20-PROPANOL-7 Loads a mixture of 73\ % argon, 20\ % methane and 7\ % propanol. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. 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). 3 CO2 Pure CO\2\. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Karl Dederichs and Fran\çois Piuz (drift velocity and diffusion) and Fran\çois Rohrbach (multiplication). 3 CO2-80-ETHANE-20 A mixture of 80\ % CO\2\ with 20\ % ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Data supplied by Diego Bettoni. 3 CO2-90-ETHANE-10 A mixture of 90\ % CO\2\ with 10\ % ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Data supplied by Diego Bettoni and Reyad Sawafti. 3 CO2-90-ISOBUTANE-10 A mixture of 90\ % CO\2\ with 10\ % isobutane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Data supplied Manfred Guckes (transport properties) and Helmut Boettcher (clustering properties). 3 ETHANE Pure ethane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Supplied by Ingo Herbst. 3 ISOBUTANE Pure isobutane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Supplied by Emile Schmoetter. Clustering properties from Helmut Boettcher. 3 METHANE Pure methane. This command is provided mainly for reasons of backwards compatibility. For new applications, consider using "-> &GAS -> HEED" for ionisation of gas mixtures due to charged particles, "-> &GAS -> MAGBOLTZ" for the electron transport properties, and "-> &GAS -> ADD" to add ion mobility data, e.g. from the H.W. Ellis et al. papers. Source: Ingo Herbst, for the drift velocity and the diffusion and from "Basic data of plasma physics, 1966", Sanborn C. Brown. 2 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: !Wul_start - parametrised data in the form of a "-> &GAS -> ADD -> function" - tabulated data of a gas property "-> &GAS -> ADD -> VS" E/p !Wul_end Beware that the "-> &GAS -> 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. The "-> &GAS -> MERGE" command should be used if you wish to combine the existing gas data with data from a gas file. Format: !W
  ADD  "-> &GAS -> ADD -> item"_1 { "-> &GAS -> ADD -> function"_1 | value_1 "-> &GAS -> ADD -> VS" ep_1 [ORDER "-> &GAS -> ADD -> order"_1] } ...
       item_2 { function_2 | value_2 VS ep_2 [ORDER order_2] } ...
       ...
!W
Example: !W
  "-> Global" pbar = 3
  "-> &GAS -> magboltz" argon 91 nitrogen 4 methane 5 ...
     e/p-range 0.05 135
  "-> 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
  "-> &GAS -> extrapolations" low-ion-mobility constant high-ion-mobility linear
!W
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 are changed from cm\²/sec.V to cm\²/\μsec.V. Finally, the mobility is added to the gas tables using the ADD statement. !W !WReferences: !W
!W
[1] !W
H.W. Ellis, R.Y. Pai, E.W. McDaniel, E.A. Mason and L.A. Viehland, !WTransport properties of gaseous ions over a wide energy range, !WAt. Data and Nucl. Data Tables 17 (1976) 177-210. !W
[2] !W
H.W. Ellis, E.W. McDaniel, D.L. Albritton, L.A. Viehland, S.L. Lin and E.A. Mason, !WTransport properties of gaseous ions over a wide energy range, part II, !WAt. Data and Nucl. Data Tables 22 (1978) 179-217. !W
[3] !W
H.W. Ellis, M.G. Thackston, E.W. McDaniel and E.A. Mason, !WTransport properties of gaseous ions over a wide energy range, part III, !WAt. Data and Nucl. Data Tables 31 (1984) 113-151. !W
[4] !W
L.A. Viehland and E.A. Mason, !WTransport properties of gaseous ions over a wide energy range, part IV, !WAt. Data and Nucl. Data Tables 60 (1995) 37-95. !W
[5] !W
J. A. Hornbeck, !WThe drift velocities of molecular and atomic ions in Helium, !WNeon and Argon, Phys. Rev. 84 (1951) 615-620. !W
[6] !W
E. C. Beaty, !WProc 5th International conference on ionisation phenomena in gasses, !WMünchen (1961), Vol 1, p 183, North Holland. !WPhys. Rev. 170 (1968) 116. !W
3 item Can be any of the following: !Wtable_start !T+P + + . ---------------------------------------------------------------------------------------- Item Explanation Unit ---------------------------------------------------------------------------------------- ATTACHMENT-COEFFICIENT Attachment coefficient/pressure 1/cm.Torr DRIFT-VELOCITY Drift velocity cm/\μsec ION-DISSOCIATION Ion dissociation coefficient 1/cm.Torr ION-MOBILITY Ion mobility cm\²/\μsec.V LONGITUDINAL-DIFFUSION Longitudinal diffusion \√p cm.\√Torr for 1\ cm LORENTZ-ANGLE Lorentz angle degrees TOWNSEND-COEFFICIENT Townsend coefficient/pressure 1/cm.Torr TRANSVERSE-DIFFUSION Transverse diffusion \√p cm.\√Torr for 1\ cm ---------------------------------------------------------------------------------------- !Wtable_end Note that the same "-> &GAS -> TABLE -> scaling"s have to be applied as for the "-> &GAS -> TABLE". 3 function The function may depend on the following variables: !Wtable_start !T+P + + . -------------------------------------------------------------------------------- Variable Meaning Unit -------------------------------------------------------------------------------- ANGLE_EB Angle between E and B degrees ATTACHMENT Attachment coefficient / p 1/cm.Torr B Magnetic field strength Tesla BOLTZMANN Boltzmann constant 1.380658 10\-23\ J/K DISS Ion dissociation coefficient 1/cm.Torr ECHARGE Electron charge 1.60217733 10\-19\ C EP Electric field / p V/cm.Torr LORENTZ Lorentz angle degrees MOBILITY Ion mobility cm\²/\μsec.V P Pressure Torr SIGMA_L Longitudinal diffusion \√ p cm.\√Torr for 1\ cm SIGMA_T Transverse diffusion \√p cm.\√Torr for 1\ cm T Temperature K TOWNSEND Townsend coefficient / p 1/cm.Torr VELOCITY Electron drift velocity cm/\μsec -------------------------------------------------------------------------------- !Wtable_end The variable EP can always be used, ANGLE_EB and B can only be used in tables prepared for magnetic fields. The transport properties can be used only insofar as they have been entered already. 3 VS If you wish to add experimental data to a table, you should prepare !Wul_start - a 1-dimensional "-> algebra -> variables -> types -> Matrix" that contains the E/p values at which the measurements were done; - a 1-dimensional Matrix that contains the corresponding measured values of the selected "-> &GAS -> ADD -> item". !Wul_end The E/p vector should in principle cover the entire range of the table. Values outside the range of the E/p vector are left untouched - no attempt is made to extrapolate. Since most items are initialised to values outside their permissible range, an error will in general be reported from the checks that are carried out while leaving the gas section. To avoid this, one can first set the item with an approximate function and then override in part with more precise values. This is illustrated here for He\+\ in He: !W
  // Experimental data
  Vector E_He_He K_He_He
     0  10.5
     6  10.3
     8  10.2
    10  10.2
    12  10.1
    15  10.0
    20   9.90
    25   9.74
    30   9.60
    40   9.28
    50   8.97
    60   8.67
    80   8.12
   100   7.67
   120   7.25
   150   6.78
   200   6.12
   250   5.60
   300   5.19
   400   4.58
   500   4.17
   600   3.81
   700   3.57

  // Scaling from Td to V/cm.Torr and from V/cm\².sec to V/cm\².\μsec
  Global E_He_He = E_He_He/(0.010354*300)
  Global K_He_He = K_He_He*1e-6
  // Fit an exponential to the shape
  Call fit_exponential(E_He_He,K_He_He,1e-8,p0,p1,p2,p3,ep0,ep1,ep2,ep3)
  // Provisionally set the mobility to the exponential function
  add ion-mobility "-> algebra -> functions -> exp"({p0}+{p1}*ep+{p2}*ep^2+{p3}*ep^3)
  // Override the values that are in the range
  add ion-mobility K_He_He vs E_He_He
!W
The E/p values in your vector do not have to coincide with the E/p values present in the table - your vectors will be interpolated at the values of the table and these interpolations are stored instead of the values from the vector. 3 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. 2 CLUSTER Enters the cluster-size distribution. You may choose between !Wul_start - entering a "-> &GAS -> CLUSTER -> parametrisation", - "-> &GAS -> CLUSTER -> listing" of all probabilities and - a "-> &GAS -> CLUSTER -> mixed" form. !Wul_end The cluster size distribution is not by itself enough to generate clusters along a track. The "-> &DRIFT -> TRACK -> EXPONENTIAL-SPACING" clustering model which uses the distribution entered here, also needs to know the "-> &GAS -> PARAMETERS -> mean" number of clusters per cm. If you use the "-> &GAS -> HEED" interface, then you 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 "-> &DRIFT -> TRACK" level that you decide which clustering model you are going to use. 3 Parametrisation In this format, you specify a parametrisation of the cluster size distribution. In the areas between absorption shells, the distribution usually follows simple power laws, but the shell structure is in general not something which can be neglected. Format: !W
  CLUSTER FUNCTION "-> &GAS -> CLUSTER -> Parametrisation -> cluster_function" [N "-> &GAS -> CLUSTER -> Parametrisation -> nmax"]
!W
Example: !W
  cluster function 1/n^3 n 15
!W
Doing this will produce a warning since, to compute probability to have a cluster size of 0, one would divide by zero. 4 cluster_function 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 between N=0 to N="-> &GAS -> CLUSTER -> Parametrisation -> nmax"-1 at integer and half-integer values. The cluster size distribution starts at a size of 0, not 1. The reason for this is that most interactions between charged particles and gas molecules result in excitation, rather than ionisation. In the absence of Penning transfers, these interactions will not lead to ionisation electrons. In case you enter a cluster spacing which only takes ionisations, and not excitations, into account, then you have to set the probability at N=0 to 0. This can most easily be done using the "-> &GAS -> CLUSTER -> Mixed" format. Samples are taken at N, N+0.5 and N+1 and the probability that is assigned for a cluster size of N is the Simpson integral over these 3 points. The rationale for this approach is that it is anticipated that an energy transfer probability divided by work will be entered, so that the derived cluster size is the ratio truncated to the next lower integer, rather than the ratio rounded to the nearest integer. You don't have to worry about the normalisation. [There is no default function.] 4 nmax Maximum cluster size that will be generated, plus one. Values between 1 and MXPAIR are permitted. If set to 1, then only clusters of size 0 will ge generated. I.e. not a single ionisation electron will be produced. [Default is MXPAIR, set to 2000 at the time of writing.] 3 Listing 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. Please note that the first number is the probability to have a cluster size of 0, i.e. a cluster without ionisation electrons. When a charged particle traverses a gas, most interactions result only in excitation, not in ionisation. If you set a "-> &GAS -> PARAMETERS -> mean" number of clusters per cm which only takes clusters into account that contain at least 1 electron, then you have to set the first probability to 0. Format: !W
  CLUSTER
  prob_size0 prob_size1
  ...
  (blank line)
!W
Example: !W
  CLUSTER
  0 0 0.1 0.2 0.5
  0.2 0.1 0

  // Note that the preceding line is left blank
!W
3 Mixed This format is to be used if you wish to enter, for small cluster sizes a measured cluster size distribution and for the larger sizes an asymptotic expression. Format: !W
  CLUSTER FUNCTION "-> &GAS -> CLUSTER -> Parametrisation -> cluster_function" [N "-> &GAS -> CLUSTER -> Parametrisation -> nmax"] OVERLAP-TABLE-AND-FUNCTION
  prob_size0 prob_size1
  ...
  (blank line)
!W
Example: !W
  CLUSTER FUNCTION 21.6/N^2 N=200 OVERLAP
  0 86 20 10
!W
There has to be a blank line after the cluster sizes. One can also simulate this format by using a "-> Do" loop: !W
  cluster
  0 86 20 10
  For i From 4 To 200 Do
     {21.6/i^2}
  Enddo

  // Note that the previous line is left blank !
!W
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. A more efficient version of the latter would be: !W
  cluster
  0 86 20 10 {21.6/"-> algebra -> functions -> row"(200)^2}

  // Note that the previous line is blank !
!W
2 COMPOSITION Establishes the Magboltz gas composition without running Magboltz. The composition is set by the "-> &GAS -> MAGBOLTZ" command and is preserved in gas files (written by "-> &GAS -> WRITE" and read with "-> &GAS -> GET"). There is therefore no need to use the COMPOSITION command when running Magboltz nor when retrieving Magboltz generated electron transport tables. The information supplied by this command is only used by the "-> &DRIFT -> methods -> microscopic" electron tracking procedures such as "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" and "-> Call -> MICROSCOPIC_AVALANCHE". This command does not provide the electron transport tables needed by the other electron tracking methods. You will therefore, in general, have to provide electron transport tables (e.g. using "-> &GAS -> TABLE") when using the COMPOSITION statement. All fractions must be strictly positive. The fractions may add up to any non-zero value - they will be normalised by Magboltz. Format: see "-> &GAS -> MAGBOLTZ" Example: !W
  composition argon 80 co2 20
!W
This will set the gas composition to 80\ % Ar and 20\ % CO\2\. 2 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 "-> &GAS -> INTERPOLATIONS" command. EXTRAPOLATE can be used as synonym for this command. Format: !W
  EXTRAPOLATIONS "-> &GAS -> EXTRAPOLATIONS -> item"1 "-> &GAS -> EXTRAPOLATIONS -> method"1 item2 method2 ...
!W
Examples: !W
  extrapolate drift: linear, diff: const, town: const
  extrapolate drift exp
!W
3 item The table item to be extrapolated, the following are known: !Wtable_start !T+P + . ------------------------------------------------------------------------ Item Description ------------------------------------------------------------------------ [HIGH-]ATTACHMENT-COEFFICIENT Attachment coefficient beyond highest E/p [HIGH-]DIFFUSION-TENSOR Diffusion tensor beyond the highest E/p [HIGH-]DISSOCIATION Ion dissociation beyond the highest E/p [HIGH-]DRIFT-VELOCITY Drift velocity beyond the highest E/p [HIGH-]EXCITATION-RATES Excitation rates beyond the highest E/p [HIGH-]ION-MOBILITY Ion mobility beyond the highest E/p [HIGH-]IONISATION-RATES Ionisation rates beyond the highest E/p [HIGH-]LONGITUDINAL-DIFFUSION Long. diffusion beyond the highest E/p [HIGH-]LORENTZ-ANGLE Lorentz angle beyond the highest E/p [HIGH-]TOWNSEND-COEFFICIENT Townsend coefficient beyond highest E/p [HIGH-]TRANSVERSE-DIFFUSION Transv. diffusion beyond the highest E/p LOW-ATTACHMENT-COEFFICIENT Attachment coefficient below first E/p LOW-DIFFUSION-TENSOR Diffusion tensor below the first E/p LOW-DISSOCIATION Ion dissociation below the first E/p LOW-DRIFT-VELOCITY Drift velocity below the first E/p LOW-EXCITATION-RATES Excitation rates below the highest E/p LOW-ION-MOBILITY Ion mobility below the first E/p LOW-IONISATION-RATES Ionisation rates below the highest E/p LOW-LONGITUDINAL-DIFFUSION Long. diffusion below the first E/p LOW-LORENTZ-ANGLE Lorentz angle below the first E/p LOW-TOWNSEND-COEFFICIENT Townsend coefficient below first E/p LOW-TRANSVERSE-DIFFUSION Transv. diffusion below the first E/p ------------------------------------------------------------------------ !Wtable_end The prefix HIGH- is optional for backwards compatibility. DIFFUSION can be used instead of LONGITUDINAL-DIFFUSION. 3 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. 2 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. The "-> &GAS -> MAGBOLTZ" and "-> &GAS -> MIX" commands set an identification string that contains a description of the gas mixture. It is advisable not to override this string. Instead, one can use the "-> Call -> GET_GAS_DATA" procedure to obtain the identifier set by these commands, and then add further information to it. The identification string is displayed in the plots using the "-> graphics -> REPRESENTATION -> item -> COMMENT" text representation. Format: !W
  GAS-IDENTIFIER string
!W
Examples: !W
  GAS-ID "Some gas"
!W
Sets a simple identification string. !W
  "-> &GAS -> temperature" 300 K
  "-> &GAS -> magboltz" argon 50 dme 50
  *** Ar++ in Ar, T=300 K, error 1 % (Mason McDaniel I, Beaty 68)
  "-> Vector" E_Ar_Ar_2 K_Ar_Ar_2
   40   2.49
   50   2.47
   60   2.45
   70   2.42
   80   2.39
   90   2.37
  100   2.34
  120   2.28
  140   2.23
  160   2.19
  180   2.15
  200   2.11

  Call "-> Call -> get_gas_data"(p,t,gasid)
  Global E_Ar_Ar_2 = p*E_Ar_Ar_2/(0.010354*t)
  Global K_Ar_Ar_2 = K_Ar_Ar_2*1e-6
  "-> &GAS -> add" ion-mobility K_Ar_Ar_2 vs E_Ar_Ar_2
  "-> &GAS -> extrapolations" low-ion-mobility constant high-ion-mobility linear
  gas-id "{gasid} with Ar++"
!W
Magboltz is used to compute electron transport properties, and these are complemented with experimental Ar mobility at the same temperature and pressure. The addition is registered in the gas identifier. 2 GET Retrieves a compact format gas description written by "-> &GAS -> 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, "-> &GAS -> Heed" initialisation information, "-> &GAS -> SRIM" energy loss, range and straggling tables, the pressure and the temperature. GET overwrites all of these. Since format version\ 8, an attempt has been made to maintain backwards compatibility of file formats. Beware however that older formats will as a rule not contain as much information as the newer versions, which may result in the failure of certain newer commands. Format: !W
  GET "-> &GAS -> GET -> file" ["-> &GAS -> GET -> member"]
!W
Example: !W
  GET gas_data.dat gas2
!W
3 file The name of the "-> dataset -> structure -> file" that contains the gas description. 3 member The name of the "-> dataset -> structure -> member" that you wish to retrieve. 2 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 "-> &DRIFT -> TRACK -> HEED" clustering model of the "-> &DRIFT -> TRACK" command. Heed initialisation is performed automatically when reloading ("-> &GAS -> GET") a gas for which an Heed initialisation has been performed. The "-> &GAS -> TEMPERATURE" and the "-> &GAS -> PRESSURE" should be specified before issuing the HEED command. Defaults are assumed if they follow the HEED command. Neither temperature nor pressure "-> &GAS -> TABLE -> 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: !W
  HEED  [ HYDROGEN  fraction ]   [ HELIUM-4  fraction ] ...
        [ NEON  fraction ]       [ ARGON  fraction ] ...
        [ KRYPTON  fraction ]    [ XENON  fraction ] ...

        [ NITROGEN  fraction ]   [ OXYGEN  fraction ] ...

        [ METHANE   fraction ]   [ ETHANE  fraction ] ...
        [ ETHENE  fraction ]     [ ACETYLENE  fraction ]  ...
        [ PROPANE  fraction ]    [ ISOBUTANE  fraction ] ...
        [ NEOPENTANE  fraction ] ...

        [ WATER  fraction ]      [ CO2  fraction ] ...
        [ DME  fraction ]        [ NITROUS-OXIDE  fraction ] ...
        [ AMMONIA  fraction ]    [ SF6 fraction ] ...
        [ CS2 fraction ] ...

        [ CF4  fraction ]        [ C2F4H2  fraction ] ...
        [ C2F5H  fraction ]      [ C3F8 fraction ]
!W
Example: !W
  "-> &GAS -> pressure" {3*760}
  Heed argon 50 ethane 50
!W
(If you have a 3\ atm 50/50 argon-ethane mixture in your chamber.) 2 INTERPOLATIONS Sets the method used to interpolate the gas tables at a given electric field strength. By default, the gas tables are interpolated using quadratic Newton polynomials. Use this statement if you wish to select splines, lower order polynomials or higher order polynomials. The interpolation method is ignored if the gas table contains only a single electric field strength. INTERPOLATE can be used as a synonym for this command. Format: !W
  INTERPOLATIONS "-> &GAS -> INTERPOLATIONS -> item"1 "-> &GAS -> INTERPOLATIONS -> method"1 item2 method2 ...
!W
Examples: !W
  interpolate drift-velocity newton 2, long-diffusion newton 1
  int townsend spline
!W
3 item The table item for which you wish to alter the interpolation method. !Wtable_start !T+P + . --------------------------------------------------------------- Keyword Meaning --------------------------------------------------------------- ATTACHMENT-COEFFICIENT Attachment coefficient of electrons DIFFUSION-TENSOR Diffusion tensor components DRIFT-VELOCITY Electron drift velocity EXCITATION-RATES Individual gas excitation rates ION-DISSOCIATION Ion dissociation coefficient ION-MOBILITY Ion mobility IONISATION-RATES Individual gas excitation rates LONGITUDINAL-DIFFUSION Longitudinal diffusion of electrons LORENTZ-ANGLE Lorentz angle of electrons TOWNSEND-COEFFICIENT Townsend coefficient of electrons TRANSVERSE-DIFFUSION Transverse diffusion of electrons --------------------------------------------------------------- !Wtable_end 3 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: !W
  INTERPOLATIONS item SPLINES
  INTERPOLATIONS item NEWTON order
!W
!Wtable_start !T+P + + . --------------------------------------------------------------- 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 --------------------------------------------------------------- !Wtable_end 2 MAGBOLTZ Invokes the Magboltz program to compute for electrons, the drift velocity, the longitudinal and transverse diffusion coefficients, the Townsend and attachment coefficients as well as the excitation and ionisation rates for the various gas molecules. Contrary to the related "-> &GAS -> MIX" instruction, Magboltz takes !D1 cross sections !W !Wcross sections for non-elastic processes into account. Furthermore, Magboltz is not limited to the 0th and 1st order terms of the spherical harmonics expansion used by MIX. Magboltz does need considerably more calculation time. In Garfield up to version\ 8, this command gave access to both version\ 1 and version\ 2 of Magboltz. These programs differed by the integration technique use: "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" for version\ 1 and "-> &GAS -> MAGBOLTZ -> MONTE-CARLO-INTEGRATION" for version\ 2. Version\ 1 was to be preferred for pure noble gases and mixtures of exclusively noble gases, without addition of quenchers or other additives. Version\ 2, which became default, was recommended for all other pure gases and for all gas mixtures. Even though these older versions of Magboltz did compute the Townsend and attachment coefficients, one used the Imonte program (from the same author) to compute these with better precision. From Garfield version\ 9 on, Magboltz version\ 7 and higher is called. This Magboltz version only does Monte Carlo integration. It can be used for gas mixtures both with and without quenchers, even if the program will be slow for the latter. Magboltz version\ 7 includes the Imonte functionality - which is therefore no longer needed. Since Magboltz takes the magnetic field into account to compute the transport properties, the "-> &MAGNETIC" section should precede the gas section. If there is a magnetic field, the program computes a drift velocity vector, otherwise a scalar. Likewise, "-> &GAS -> TEMPERATURE" and "-> &GAS -> 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 "-> &GAS -> TABLE -> 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: !W
  MAGBOLTZ [ "-> &GAS -> MAGBOLTZ -> ingredient -> HYDROGEN" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> DEUTERIUM" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HELIUM-3-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HELIUM-3-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HELIUM-4-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HELIUM-4-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NEON-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NEON-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ARGON-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ARGON-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> KRYPTON-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> KRYPTON-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> XENON-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> XENON-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NITROGEN-ANISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NITROGEN-ISOTROPIC" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> OXYGEN" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> OZONE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> FLUORINE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CAESIUM" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> MERCURY" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> METHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> DEUTERATED-METHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ETHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ETHENE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ACETYLENE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> PROPANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CYCLOPROPANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> PROPENE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ISOBUTANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> N-BUTANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NEOPENTANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> N-PENTANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> METHANOL" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> ETHANOL" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> PROPANOL" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CARBON-MONOXIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CARBON-DIOXIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> WATER" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NITRIC-OXIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> NITROUS-OXIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> METHYLAL" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> DME" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> TRIFLUOROMETHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> TRIFLUOROBROMOMETHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> TETRAFLUOROMETHANE" "-> &GAS -> MAGBOLTZ -> frac" ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> TETRAFLUOROETHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HEXAFLUOROETHANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> OCTAFLUOROPROPANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> BORON-TRIFLUORIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> SULPHUR-HEXAFLUORIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> AMMONIA" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CARBON-DISULPHIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> CARBONYL-SULPHIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> HYDROGEN-SULPHIDE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> GERMANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> SILANE" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> REID-STEP" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> MAXWELL-MODEL" frac ] ...
           [ "-> &GAS -> MAGBOLTZ -> ingredient -> REID-RAMP" frac ] ...


           [ [ "-> &GAS -> MAGBOLTZ -> ELECTRIC-FIELD"-RANGE emin emax ] ...
                [ N-E ne ] ...
                [ LINEAR-E-SCALE | LOGARITHMIC-E-SCALE ] | ...
             [ ELECTRIC-FIELD {efield1 efield2 ... | vector} ] ] ...
           [ [ "-> &GAS -> MAGBOLTZ -> ANGLE"-RANGE amin amax ] [ N-ANGLE nangle ] | ...
             [ ANGLE {angle1 angle2 ... | vector} ] ] ...
           [ [ "-> &GAS -> MAGBOLTZ -> B-FIELD"-RANGE bmin bmax ] [ N-B nb ] | ...
             [ B-FIELD {bfield1 bfield2 ... | vector} ] ] ...

           [ NOPLOT-DISTRIBUTION-FUNCTIONS | "-> &GAS -> MAGBOLTZ -> PLOT-DISTRIBUTION-FUNCTIONS" ] ...
           [ NOPLOT-CROSS-SECTIONS | "-> &GAS -> MAGBOLTZ -> PLOT-CROSS-SECTIONS" ] ...
           [ NOKEEP | "-> &GAS -> MAGBOLTZ -> KEEP" ] ...
           [ NOPRINT | "-> &GAS -> MAGBOLTZ -> PRINT" ]

           [ "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" ...
              [ "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SECOND-ORDER-TERMS" | "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> FIRST-ORDER-TERMS" | "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ORDERS" n ] ...
              [ NOITERATE-ALPHA | "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA" ] ...
              [ "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SWITCH" [alpha/pressure] | NOSWITCH ] ...
              [ F0-TRANSVERSE-DIFFUSION | ...
                H1-TRANSVERSE-DIFFUSION | ...
                MEAN-ENERGY-TRANSVERSE-DIFFUSION ] ...
              [ F0-LONGITUDINAL-DIFFUSION | ...
                H1-LONGITUDINAL-DIFFUSION | ...
                G0-LONGITUDINAL-DIFFUSION ] | ...
           [ "-> &GAS -> MAGBOLTZ -> MONTE-CARLO-INTEGRATION" ...
              [ "-> &GAS -> MAGBOLTZ -> MONTE-CARLO-INTEGRATION -> COLLISIONS" ncoll ] ] ] ...

           [ "-> &GAS -> MAGBOLTZ -> MOBILITY" mob ]
!W
Example: !W
  magboltz argon 50 ethane 50
!W
(You've a mixture of 50\ % argon and 50\ % ethane in your chamber, and you trust the default settings for the electric field range, for the magnetic field and for the angles between E and B field as well as the default precision.) 3 ingredient 4 HYDROGEN Hydrogen gas. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\HYDROGEN\H2\ Structure H\2\ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------------ Triplet excitation HYDROGEN-TRIPLET 8.85 eV Singlet excitation HYDROGEN-SINGLET 12.0 eV Ionisation HYDROGEN-IONISATION 15.427 eV ------------------------------------------------------------ !Wtable_end Last update 2001 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 DEUTERIUM Deuterium gas. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\DEUTERIUM\D2\ Structure D\2\ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------------ Triplet excitation DEUTERIUM-TRIPLET 8.85 eV Singlet excitation DEUTERIUM-SINGLET 12.0 eV Ionisation DEUTERIUM-IONISATION 15.427 eV ------------------------------------------------------------ !Wtable_end Last update 1998 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 HELIUM-3-ANISOTROPIC Helium 3, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\HELIUM-3\HELIUM-3-ANISOTROPIC\ Structure \3\He Cross section No plot available (similar to \4\He) Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------------ Triplet excitation HELIUM-3-TRIPLET 19.82 eV Singlet excitation HELIUM-3-SINGLET 20.61 eV Ionisation HELIUM-3-IONISATION 24.587 eV ------------------------------------------------------------ !Wtable_end Last update 2002 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 HELIUM-3-ISOTROPIC Helium 3, isotropic version (not default for helium 3). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\HELIUM-3-ISOTROPIC\ Structure \3\He Cross section No plot available (similar to \4\He) Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------------------- Triplet excitation HELIUM-3-ISOTROPIC-TRIPLET 19.82 eV Singlet excitation HELIUM-3-ISOTROPIC-SINGLET 20.6 eV Ionisation HELIUM-3-ISOTROPIC-IONISATION 24.59 eV --------------------------------------------------------------------- !Wtable_end Last update 1992 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 HELIUM-4-ANISOTROPIC Helium 4, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\HELIUM-4\HELIUM-4-ANISOTROPIC\ Structure \4\He Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------------ Triplet excitation HELIUM-4-TRIPLET 19.82 eV Singlet excitation HELIUM-4-SINGLET 20.61 eV Ionisation HELIUM-4-IONISATION 24.587 eV ------------------------------------------------------------ !Wtable_end Last update 2002 Quality Best known gas (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 HELIUM-4-ISOTROPIC Helium 4, isotropic version (not default for helium 4). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\HELIUM-4-ISOTROPIC\ Structure \4\He Cross section \ Energy levels \ !Wtable_start !T+ + R . ---------------------------------------------------------------------- Level description Identifier Energy [eV] ---------------------------------------------------------------------- Triplet excitation HELIUM-4-ISOTROPIC-TRIPLET 19.82 eV Singlet excitation HELIUM-4-ISOTROPIC-SINGLET 20.61 eV Ionisation HELIUM-4-ISOTROPIC-IONISATION 24.587 eV ---------------------------------------------------------------------- !Wtable_end Last update 1997 Quality Best known gas (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NEON-ANISOTROPIC Neon, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NEON\NEON-ANISOTROPIC\ Structure Ne Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------------------------------- 1s\5\ excitation NEON-1S5 16.618 eV 1s\4\ excitation NEON-1S4 16.670 eV 1s\3\ excitation NEON-1S3 16.715 eV 1s\2\ excitation NEON-1S2 16.857 eV 2p\2\-2p\10\ excitations NEON-2P2-2P10 18.381 eV 2p\1\ excitation NEON-2P1 18.965 eV 2s excitations NEON-2S 19.663 eV 3d+3s excitations NEON-3D-3S 20.033 eV 3p excitations NEON-3P 20.200 eV Ionisation NEON-IONISATION 21.56 eV -------------------------------------------------------------------------------- !Wtable_end Last update 2003 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NEON-ISOTROPIC Neon, isotropic version (not default for neon). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NEON-ISOTROPIC\ Structure Ne Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------------------------------------------ 1s\5\ excitation NEON-ISOTROPIC-1S5 16.618 eV 1s\4\ excitation NEON-ISOTROPIC-1S4 16.670 eV 1s\3\ excitation NEON-ISOTROPIC-1S3 16.715 eV 1s\2\ excitation NEON-ISOTROPIC-1S2 16.857 eV 2p\2\-2p\10\ excitations NEON-ISOTROPIC-2P2-2P10 18.381 eV 2p\1\ excitation NEON-ISOTROPIC-2P1 18.965 eV 2s excitations NEON-ISOTROPIC-2S 19.663 eV 3d+3s excitations NEON-ISOTROPIC-3D-3S 20.033 eV 3p excitations NEON-ISOTROPIC-3P 20.200 eV Ionisation NEON-ISOTROPIC-IONISATION 21.56 eV ------------------------------------------------------------------------------------------ !Wtable_end Last update 2003 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 ARGON-ANISOTROPIC Argon, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\ARGON\ARGON-ANISOTROPIC\ Structure Ar Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------- s-level excitations ARGON-S 11.55 eV p-level excitations ARGON-P 13.0 eV d-level excitations ARGON-D 14.0 eV Ionisation ARGON-IONISATION 15.70 eV -------------------------------------------------------- !Wtable_end Last update 2002 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 ARGON-ISOTROPIC Argon, isotropic version (not default for argon). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\ARGON-ISOTROPIC\ Structure Ar Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------------------- s-level excitation ARGON-ISOTROPIC-S 11.55 eV p-level excitation ARGON-ISOTROPIC-P 13.0 eV d-level excitation ARGON-ISOTROPIC-D 14.0 eV Ionisation ARGON-ISOTROPIC-IONISATION 15.70 eV -------------------------------------------------------------------- !Wtable_end Last update 2002 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 KRYPTON-ANISOTROPIC Krypton, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\KRYPTON\KRYPTON-ANISOTROPIC\ Structure Kr Cross section \ Energy levels \ !Wtable_start !T+ + R . ---------------------------------------------------------- Level description Identifier Energy [eV] ---------------------------------------------------------- s-level excitations KRYPTON-S 9.915 eV p-level excitations KRYPTON-P 11.304 eV d+p-level excitations KRYPTON-D-P 11.998 eV Other excitations KRYPTON-REST 12.75 eV Ionisation KRYPTON-IONISATION 13.996 eV ---------------------------------------------------------- !Wtable_end Last update 2002 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 KRYPTON-ISOTROPIC Krypton, isotropic version (not default for krypton). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\KRYPTON-ISOTROPIC\ Structure Kr Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------------------- s-level excitations KRYPTON-ISOTROPIC-S 9.915 eV p-level excitations KRYPTON-ISOTROPIC-P 11.304 eV d+p-level excitations KRYPTON-ISOTROPIC-D-P 11.998 eV Other excitations KRYPTON-ISOTROPIC-REST 12.75 eV Ionisation KRYPTON-ISOTROPIC-IONISATION 13.996 eV -------------------------------------------------------------------- !Wtable_end Last update 2001 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 XENON-ANISOTROPIC Xenon, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\XENON\XENON-ANISOTROPIC\ Structure Xe Cross section \ Energy levels \ !Wtable_start !T+ + R . ---------------------------------------------------------- Level description Identifier Energy [eV] ---------------------------------------------------------- 8.315 eV excitation XENON-1 8.315 eV 9.447 eV excitation XENON-2 9.447 eV 9.917 eV excitation XENON-3 9.917 eV 11.70 eV excitation XENON-4 11.70 eV Ionisation XENON-IONISATION 12.13 eV ---------------------------------------------------------- !Wtable_end Last update 2003 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 XENON-ISOTROPIC Xenon, isotropic version (not default for xenon). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\XENON-ISOTROPIC\ Structure Xe Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------------------- 8.315 eV excitation XENON-ISOTROPIC-1 8.315 eV 9.447 eV excitation XENON-ISOTROPIC-2 9.447 eV 9.917 eV excitation XENON-ISOTROPIC-3 9.917 eV 11.70 eV excitation XENON-ISOTROPIC-4 11.70 eV Ionisation XENON-ISOTROPIC-IONISATION 12.13 eV -------------------------------------------------------------------- !Wtable_end Last update 2003 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NITROGEN-ANISOTROPIC Nitrogen, anisotropic version (default). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NITROGEN\NITROGEN-ANISOTROPIC\N2\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------------- Triplet 1 excitation NITROGEN-TRIPLET-1 6.17 eV Triplet 3 excitation NITROGEN-TRIPLET-3 7.35 eV Triplet 5 excitation NITROGEN-TRIPLET-5 7.80 eV Triplet 7 excitation NITROGEN-TRIPLET-7 11.03 eV Triplet 8 excitation NITROGEN-TRIPLET-8 11.87 eV Singlet 2 excitation NITROGEN-SINGLET-2 8.55 eV Singlet 5 excitation NITROGEN-SINGLET-5 13.0 eV Ionisation NITROGEN-IONISATION 15.60 eV --------------------------------------------------------------- !Wtable_end Note The lowest triplet A\3\\Σ level at 6.2\ eV is metastable with a long life. The level can not be quenched by Penning transfer in most of the typical quenchers. So it floats around the chamber as an excited neutral and, on collision with a metal or insulating surface, will remove an electron into the gas and de-excite. The resultant electron current is not time-correlated with the production mechanism since the motion of the neutral excited nitrogen is very slow and can occur many milliseconds or seconds later. (Steve Biagi, January 2009.) Last update 2004 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NITROGEN-ISOTROPIC Nitrogen gas, isotropic version (not default for nitrogen gas). !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NITROGEN-ISOTROPIC\N2-ISOTROPIC\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------------------------- Level description Identifier Energy [eV] ------------------------------------------------------------------------- Triplet 1 excitation NITROGEN-ISOTROPIC-TRIPLET-1 6.17 eV Triplet 3 excitation NITROGEN-ISOTROPIC-TRIPLET-3 7.35 eV Triplet 5 excitation NITROGEN-ISOTROPIC-TRIPLET-5 7.80 eV Triplet 7 excitation NITROGEN-ISOTROPIC-TRIPLET-7 11.03 eV Triplet 8 excitation NITROGEN-ISOTROPIC-TRIPLET-8 11.87 eV Singlet 2 excitation NITROGEN-ISOTROPIC-SINGLET-2 8.55 eV Singlet 5 excitation NITROGEN-ISOTROPIC-SINGLET-5 13.0 eV Ionisation NITROGEN-ISOTROPIC-IONISATION 15.60 eV ------------------------------------------------------------------------- !Wtable_end Note The lowest triplet A\3\\Σ level at 6.2\ eV is metastable with a long life. The level can not be quenched by Penning transfer in most of the typical quenchers. So it floats around the chamber as an excited neutral and, on collision with a metal or insulating surface, will remove an electron into the gas and de-excite. The resultant electron current is not time-correlated with the production mechanism since the motion of the neutral excited nitrogen is very slow and can occur many milliseconds or seconds later. (Steve Biagi, January 2009.) Last update 2004 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 OXYGEN Oxygen gas, with 3-body attachment. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\OXYGEN\O2\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . -------------------------------------------------------------- Level description Identifier Energy [eV] -------------------------------------------------------------- Excitation A1 OXYGEN-A1 0.977 eV Excitation B1 OXYGEN-B1 1.627 eV Excitation C1+C3 OXYGEN-C1-C3 4.50 eV Dissociation A3 OXYGEN-DISSOCIATION-A3 6.10 eV Dissociation B3 OXYGEN-DISSOCIATION-B3 8.40 eV Other excitations OXYGEN-REST 9.30 eV Ionisation OXYGEN-IONISATION 12.072 eV -------------------------------------------------------------- !Wtable_end Last update 2004 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 OZONE Ozone. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\OZONE\O3\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- Excitation Chappuis OZONE-CHAPPUIS 1.50 eV Excitation Hartley OZONE-HARTLEY 4.85 eV Other excitations OZONE-REST 9.00 eV Ionisation OZONE-IONISATION 12.75 eV --------------------------------------------------------- !Wtable_end Last update 2002 Quality Good (3*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 FLUORINE Fluorine gas, from W.L. Morgan. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\FLUORINE\F2\ Structure F\2\ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- 3.16 eV excitation FLUORINE-1 3.16 eV 4.34 eV excitation FLUORINE-2 4.34 eV 11.57 eV excitation FLUORINE-3 11.57 eV 13.08 eV excitation FLUORINE-4 13.08 eV Ionisation FLUORINE-IONISATION 15.69 eV --------------------------------------------------------- !Wtable_end Last update Not known Quality Low (2*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 CAESIUM C\æsium vapour, without dimers. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\CAESIUM\CESIUM\CS\ Structure Cs Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- P 1/2 excitation CAESIUM-P12 1.3859 eV P 3/2 excitation CAESIUM-P32 1.4546 eV D 3/2 + D 5/2 excitation CAESIUM-D32-D52 1.7977 eV S 1/2 excitation CAESIUM-S12 2.2981 eV Other excitations CAESIUM-REST 2.6986 eV Ionisation CAESIUM-IONISATION 3.8926 eV --------------------------------------------------------- !Wtable_end Last update 2001 Quality Low (2*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 MERCURY Mercury vapour, including dimers, isotropic cross sections. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\MERCURY\HG\HG2\ Structure Hg, Hg\2\ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- Dimer super excitation MERCURY-DIMER-SUPER -0.040 eV Dimer excitation MERCURY-DIMER 0.040 eV 3P0 excitation MERCURY-3P0 4.667 eV 3P1 excitation MERCURY-3P1 4.887 eV 3P2 excitation MERCURY-3P2 5.461 eV 1P1 excitation MERCURY-1P1 6.704 eV 1S0 excitation MERCURY-1S0 7.926 eV Other excitations MERCURY-REST 8.60 eV Ionisation MERCURY-IONISATION 10.4375 eV --------------------------------------------------------- !Wtable_end Last update 2003 Quality Low (2*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 METHANE Methane, anisotropic description. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\METHANE\CH4\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ----------------------------------------------------------------- Level description Identifier Energy [eV] ----------------------------------------------------------------- 9 eV dissociation METHANE-DISSOCIATION-1 9.0 eV 10 eV dissociation METHANE-DISSOCIATION-2 10.0 eV 11 eV dissociation METHANE-DISSOCIATION-3 11.0 eV 11.8 eV dissociation METHANE-DISSOCIATION-4 11.8 eV Ionisation METHANE-IONISATION 12.99 eV ----------------------------------------------------------------- !Wtable_end Last update 2004 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 DEUTERATED-METHANE Deuterated methane. !WStructure:

!WCross section:

Alternative names: !Wul_start - DEUTERATED-METHANE - DH4 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 ETHANE Ethane. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\ETHANE\C2H6\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ----------------------------------------------------- Level description Identifier Energy [eV] ----------------------------------------------------- 8.2 eV excitation ETHANE-1 8.2 eV 10.3 eV excitation ETHANE-2 10.3 eV 17.0 eV excitation ETHANE-3 17.0 eV Ionisation ETHANE-IONISATION 11.52 eV ----------------------------------------------------- !Wtable_end Last update 1999 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 ETHENE Ethene. !WStructure:

!WCross section:

Alternative names: !Wul_start - ETHENE - ETHYLENE - C2H4 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 ACETYLENE Acetylene !WStructure:

!WCross section:

Alternative names: !Wul_start - ACETYLENE - ETHYNE - C2H2 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 PROPANE Propane, not to be confused with cyclo propane. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\PROPANE\C3H8\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------------ 7.7 eV excitation PROPANE-1 7.7 eV 10.0 eV excitation PROPANE-2 10.0 eV 17.0 eV excitation PROPANE-3 17.0 eV Ionisation PROPANE-IONISATION 10.95 eV ------------------------------------------------------ !Wtable_end Last update 1999 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 CYCLOPROPANE Cyclopropane, not to be confused with propane nor with its isomer propene. !WStructure:

!WCross section:

Alternative names: !Wul_start - CYCLOPROPANE - CYCLO-PROPANE - CYCLO-C3H6 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 PROPENE Propene, not to be confused with its isomer, cyclopropane. !WStructure:

!WCross section:

Alternative names: !Wul_start - PROPENE - PROPYLENE - C3H6 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 ISOBUTANE Isobutane, not to be confused with n-butane. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\ISOBUTANE\IC4H10\ISO-C4H10\C4H10\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ----------------------------------------------------- Level description Identifier Energy [eV] ----------------------------------------------------- 7.4 eV excitation ISOBUTANE-1 7.40 eV 9.7 eV excitation ISOBUTANE-2 9.70 eV 17 eV excitation ISOBUTANE-3 17.0 eV Ionisation ISOBUTANE-IONISATION 10.67 eV ----------------------------------------------------- !Wtable_end Last update 1999 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 N-BUTANE n-Butane, not to be confused with isobutane. !WStructure:

!WCross section:

Alternative names: !Wul_start - N-BUTANE - N-C4H10 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 NEOPENTANE Neopentane, not to be confused with n-pentane. !WStructure:

!WCross section:

Alternative names: !Wul_start - NEOPENTANE - NEO-PENTANE - NEO-C5H12 - C5H12 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 N-PENTANE n-Pentane, not to be confused with neopentane. !WStructure:

!WCross section:

Alternative names: !Wul_start - N-PENTANE - N-C5H12 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 METHANOL Methanol. !WStructure:

!WCross section:

Alternative names: !Wul_start - METHANOL - METHYL-ALCOHOL - WOOD-ALCOHOL - CH3OH !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 ETHANOL Ethanol. !WStructure:

!WCross section:

Alternative names: !Wul_start - ETHANOL - ETHYL-ALCOHOL - GRAIN-ALCOHOL - C2H5OH !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 PROPANOL 2-Propanol, not the (possibly more common) isomer 1-propanol. !WStructure:

!WCross section:

Alternative names: !Wul_start - PROPANOL - 2-PROPANOL - ISO-PROPANOL - ISOPROPANOL - ISOPROPYL-ALCOHOL - C3H7OH !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 CARBON-MONOXIDE Carbon monoxide. !WStructure:

!WCross section:

Alternative names: !Wul_start - CARBON-MONOXIDE - CO !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 CARBON-DIOXIDE Carbon dioxide. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\CARBON-DIOXIDE\CO2\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------ 7.9 eV excitation CO2-1 7.9 eV 8.9 eV excitation CO2-2 8.9 eV 10.5 eV excitation CO2-3 10.5 eV 12.2 eV excitation CO2-4 12.2 eV 13.2 eV excitation CO2-5 13.2 eV 15.0 eV excitation CO2-6 15.0 eV Ionisation CO2-IONISATION 13.773 eV ------------------------------------------------ !Wtable_end Last update 2004 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 WATER Water vapour. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\WATER\WATER-VAPOUR\H2O\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------ 4.20 eV excitation H2O-1 4.20 eV 7.40 eV excitation H2O-2 7.40 eV 13.1 eV excitation H2O-3 13.1 eV Ionisation H2O-IONISATION 12.61 eV ------------------------------------------------ !Wtable_end Last update 2004 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NITRIC-OXIDE Nitric oxide. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NITRIC-OXIDE\NITROGEN-MONOXIDE\NO\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- 6.10 eV excitation NITRIC-OXIDE-1 6.10 eV Ionisation NITRIC-OXIDE-IONISATION 9.2644 eV --------------------------------------------------------- !Wtable_end Last update 1995 Quality Low (2*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 NITROUS-OXIDE Nitrous oxide. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\NITROUS-OXIDE\DINITROGEN-MONOXIDE\LAUGHING-GAS\N2O\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- 4.06 eV excitation NITROUS-OXIDE-1 4.06 eV 8.50 eV excitation NITROUS-OXIDE-2 8.50 eV 9.60 eV excitation NITROUS-OXIDE-3 9.60 eV Ionisation NITROUS-OXIDE-IONISATION 12.886 eV --------------------------------------------------------- !Wtable_end Last update 2004 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 METHYLAL Methylal, "hot" version. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\METHYLAL\METHYLAL-HOT\DIMETHOXYMETHANE\DMM\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------- 6.3 eV excitation METHYLAL-1 6.3 eV 8.3 eV excitation METHYLAL-2 8.3 eV Ionisation METHYLAL-IONISATION 10.0 eV --------------------------------------------------- !Wtable_end Last update 1988 Quality Low (2*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 DME DME. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\DME\DIMETHYL-ETHER\METHOXYMETHANE\METHYL-ETHER\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . ------------------------------------------------ Level description Identifier Energy [eV] ------------------------------------------------ 7.7 eV excitation DME-1 7.70 eV 8.5 eV excitation DME-2 8.50 eV Ionisation DME-IONISATION 10.04 eV ------------------------------------------------ !Wtable_end Last update 1998 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 TRIFLUOROMETHANE Trifluoromethane. !WStructure:

!WCross section:

Alternative names: !Wul_start - TRIFLUOROMETHANE - FREON-23 - CHF3 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 TRIFLUOROBROMOMETHANE Trifluorobromomethane. !WStructure:

!WCross section:

Alternative names: !Wul_start - TRIFLUOROBROMOMETHANE - HALON-1301 - FREON-13B1 - CF3BR !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 TETRAFLUOROMETHANE Tetrafluoromethane. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\CF4\FREON-14\FREON\TETRAFLUOROMETHANE\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- Dissociation CF4-DISSOCIATION 12.5 eV Ionisation CF4-IONISATION 15.90 eV --------------------------------------------------------- !Wtable_end Last update 2001 Quality Excellent (5*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 TETRAFLUOROETHANE Tetrafluoroethane and pentafluoroethane. For the time being, the available data is not sufficient to supply separate cross sections for these 2 compounds. !WStructure:

!WCross section:

Alternative names: !Wul_start - TETRAFLUOROETHANE - C2H2F4 - C2F4H2 - FREON-134 - FREON-134-A - PENTAFLUOROETHANE - C2HF5 - C2F5H - FREON-125 - ZYRON-125 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 PENTAFLUOROETHANE See TETRAFLUOROETHANE. 4 HEXAFLUOROETHANE Hexafluoroethane. !WStructure:

!WCross section:

Alternative names: !Wul_start - HEXAFLUOROETHANE - C2F6 - FREON-116 - ZYRON-116 - ZYRON-116-N5 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 OCTAFLUOROPROPANE Octafluoropropane. !WStructure:

!WCross section:

Alternative names: !Wul_start - OCTAFLUOROPROPANE - R218 - FREON-218 - PERFLUOROPROPANE - RC-218 - PFC-218 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 BORON-TRIFLUORIDE Boron trifluoride. !Wdl_start !T+ + ------------------------------------------------------------------------------------------------ Name ------------------------------------------------------------------------------------------------ Identifiers \\BF3\BORON-TRIFLUORIDE\ Structure \ Cross section \ Energy levels \ !Wtable_start !T+ + R . --------------------------------------------------------- Level description Identifier Energy [eV] --------------------------------------------------------- Excitation BF3-EXCITATION 10.0 eV Ionisation BF3-IONISATION 15.56 eV --------------------------------------------------------- !Wtable_end Last update 2001 Quality Very good (4*) ------------------------------------------------------------------------------------------------ !Wdl_end 4 SULPHUR-HEXAFLUORIDE Sulphur hexafluoride !WStructure:

!WCross section:

Alternative names: !Wul_start - SULPHUR-HEXAFLUORIDE - SULFUR-HEXAFLUORIDE - SF6 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 AMMONIA Ammonia. !WStructure:

!WCross section:

Alternative names: !Wul_start - AMMONIA - NH3 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 CARBON-DISULPHIDE Carbon disulphide. !WStructure:

!WCross section:

Alternative names: !Wul_start - CARBON-DISULPHIDE - CARBON-DISULFIDE - CS2 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 CARBONYL-SULPHIDE Carbonyl sulphide. !WStructure:

!WCross section:

Alternative names: !Wul_start - CARBONYL-SULPHIDE - CARBONYL-SULFIDE - COS !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 HYDROGEN-SULPHIDE Hydrogen sulphide. !WStructure:

!WCross section:

Alternative names: !Wul_start - HYDROGEN-SULPHIDE - HYDROGEN-SULFIDE - HEPATIC-ACID - SEWER-GAS - SULFUR-HYDRIDE - DIHYDROGEN-MONOSULFIDE - DIHYDROGEN-MONOSULPHIDE - SULPHUR-HYDRIDE - STINK-DAMP - SULFURATED-HYDROGEN - H2S !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 GERMANE Germane. !WStructure:

!WCross section:

Alternative names: !Wul_start - GERMANE - GERMANIUM-HYDRIDE - GERMANIUM-TETRAHYDRIDE - GERMANOMETHANE - MONOGERMANE - GEH4 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 SILANE Silane. !WStructure:

!WCross section:

Alternative names: !Wul_start - SILANE - SILICON-HYDRIDE - SILICON-TETRAHYDRIDE - SILICANE - MONOSILANE - SIH4 !Wul_end Excited states: !Wdl_start !T+ + -------------------------------------- Level description Energy [eV] -------------------------------------- -------------------------------------- !Wdl_end 4 REID-STEP The Reid step, one of the models used for calibrating the type of calculations that Magboltz performs. 4 REID-RAMP The Reid ramp, one of the models used for calibrating the type of calculations that Magboltz performs. 4 MAXWELL-MODEL The Maxwell model, one of the models used for calibrating the type of calculations that Magboltz performs. 3 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.] 3 ELECTRIC-FIELD Magboltz will compute the transport properties either for electric fields that are regularly distributed within a range, or for a set of fields that you specify. !Wul_start - To request calculations for a range, use the keyword ELECTRIC-FIELD-RANGE followed by a minimum and a maximum electric field specified in V/cm, or use the keyword E/P-RANGE followed by a minimum and a maximum E/p in V/cm.Torr. In either case, you can set the number of points with N-E or N-E/P (which are synonyms) and you have the choice between linear and logarithmic spacing of the points. - To request transport properties for a set of fields, use the ELECTRIC-FIELD or E/P keyword followed either by a list of fields or by the name of a "-> algebra -> variables -> types -> Matrix" that contains the field values. In either case, ensure that all fields are strictly positive and that they are in strictly increasing order. !Wul_end Make sure that the all fields present in your chamber are covered by the table and do not rely on the "-> &GAS -> EXTRAPOLATIONS". Pay particular attention to the region in the immediate vicinity of wires. Use e.g. the field section "-> &FIELD -> CHECK" "-> &FIELD -> CHECK -> WIRES" commands to determine the field there. Try to be reasonable when selecting the number of electric fields at which you run Magboltz. On the one hand the number of points must be large enough so as to represent any fine structure that may be present in the transport properties. On the other hand, an excessively large number of points may lead to oscillations in the interpolation. It is permissible to request transport properties for only a single field, for instance to study the dependence of the transverse diffusion on the magnetic field. The interpolation methods need not be specified in this case and only constant extrapolations can be used. If you ask for a small number of points, e.g. 2, then you can only request low order "-> &GAS -> INTERPOLATIONS". [By default E ranges from 100\ V/cm to 100000\ V/cm in 20 logarithmically spaced steps.] 3 B-FIELD A magnetic field can have a major impact on the direction of motion of electrons, as well as on the transverse diffusion. These effects depend not only on the magnetic field strength, but also on the "-> &GAS -> MAGBOLTZ -> ANGLE" between the electric and magnetic fields. You can either ask Magboltz to compute the transport properties at evenly spaced magnetic fields within a range or for a set of magnetic fields that you specify. !Wul_start - To ask for a range, you use the MAGNETIC-FIELD-RANGE keyword followed by a minimum and a maximum magnetic field specified in Tesla, irrespective of the units used when entering the magnetic field. You can set the number of points with N-B. - To request transport properties for a set of fields, use the MAGNETIC-FIELD keyword followed either by a list of fields or by the name of a "-> algebra -> variables -> types -> Matrix" that contains the field values. In either case, ensure that the fields are expressed in Tesla, also be sure that they are strictly positive. !Wul_end If you ask for only 1 magnetic field strength and only 1 angle between E and B, then Magboltz will generate a 1-dimensional table for which you have greater control over the "-> &GAS -> INTERPOLATIONS" and "-> &GAS -> EXTRAPOLATIONS" methods. These parameters can not be used if there is no magnetic field. [If the magnetic field can be determined to be constant or zero, then Magboltz by default only computes a table for the magnetic field that is present in the chamber. If the B field is not constant, but of known range, then Magboltz will by default be run for 6 magnetic fields ranging from the minimum field to the maximum field present in the chamber. In all other cases, it will compute tables for 0, 1, 2, 3, 4 and 5 T.] 3 ANGLE 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. You can either ask Magboltz to compute the transport properties for angles between E and B that are evenly spaced over a range, or for a user-specified set of angles between the 2 fields: !Wul_start - To ask for a range, you use the ANGLE-RANGE keyword followed by a minimum and a maximum angle in degrees. Ensure that the range is entirely contained in [0\°,\ 90\°]. You can set the number of angles with N-ANGLES. - To request transport properties for a set of angles, use the ANGLES keyword followed either by a list of angles or by the name of a "-> algebra -> variables -> types -> Matrix" that contains the angles. In either case, ensure that the angles are expressed in degrees, also be sure that they are in the range [0\°,\ 90\°]. It is advisable to use this format, with ANGLE=90, if your chamber is such that E is always perpendicular to B. It is bad practice to set ANGLE=0 in TPCs where E is parallel with B in the drift volume. Other orientations occur in the read-out chambers, and these orientations have impact on the resolution of the TPC. !Wul_end If you ask for only 1 magnetic field strength and only 1 angle between E and B, then Magboltz will generate a 1-dimensional table for which you have greater control over the "-> &GAS -> INTERPOLATIONS" and "-> &GAS -> EXTRAPOLATIONS" methods. These parameters can not be used if there is no magnetic field. [Magboltz will, if B is non-zero, by default be asked to compute tables for angles of 0\°, 30\°, 60\° and 90\° between the E and B field.] 3 PLOT-DISTRIBUTION-FUNCTIONS Requests for each E, and if applicable each B and E-B orientation, plots of the electron distribution functions. Use the "-> &GAS -> MAGBOLTZ -> KEEP" option if you need more flexibility. !Wul_start - When using analytic integration, which is only available with Garfield versions\ 7 and earlier, F0, F1, F2 and F3 will be plotted. 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 "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SECOND-ORDER-TERMS" (or "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ORDERS" 2) and for a reasonably accurate F3 you should specify ORDERS 3. Both are incompatible with the option "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA" which enables a more precise computation of the Townsend coefficient. F0 is plotted with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", F1 as "-> graphics -> REPRESENTATION -> item -> FUNCTION-2", F2 as "-> graphics -> REPRESENTATION -> item -> FUNCTION-3" and F3 as "-> graphics -> REPRESENTATION -> item -> FUNCTION-4". - When using Monte Carlo integration, the energy distribution function is not expanded in a series, and only a single graph is displayed. This function is plotted with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", !Wul_end [This option is off by default, but it is switched on automatically in case there are concerns about the validity of the energy range.] 3 PLOT-CROSS-SECTIONS Requests for each E, and if applicable each B and E-B orientation, plots of the electron distribution functions. Plotted is the quantity used inside Magboltz: the stp cross section scaled by pressure and temperature, multiplied with the Loschmidt number - a quantity that can be interpreted as the reciprocal of the mean free path. This option is provided to enable a rapid inspection of the cross sections. The "-> &GAS -> MAGBOLTZ -> KEEP" option is recommended to make better quality graphs. The total cross section is plotted with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the elastic cross section with "-> graphics -> REPRESENTATION -> item -> FUNCTION-2", the attachment cross section with "-> graphics -> REPRESENTATION -> item -> FUNCTION-3" and the ionisation cross sections for the various components with "-> graphics -> REPRESENTATION -> item -> FUNCTION-4". [This option is off by default.] 3 KEEP Requests the cross section and the energy distribution function to be kept as global variables. This option is used if you need more flexibility in making graphs than can be obtained with the "-> &GAS -> MAGBOLTZ -> PLOT-DISTRIBUTION-FUNCTIONS" and "-> &GAS -> MAGBOLTZ -> PLOT-CROSS-SECTIONS" options. The energy range over which these quantities are stored is set by the Magboltz program so as to obtain optimal accuracy for the calculation of the transport parameters. This range can not be set directly from the command line. However, the maximum energy is strongly influenced by the electric field, which can therefore be used to select the range. The names of the global variables are shown in the table below. In order not to overwrite parameters from earlier calculations, a sequential number "n" is appended to the name. The names are displayed while the command executes. !Wtable_start !T+ + + . --------------------------------------------------------------- Name Quantity Unit --------------------------------------------------------------- E_n Energy eV F_n Energy distribution function Integral normalised to 1 CST_n Total cross section cm\²/molecule CSE_n Elastic cross section cm\²/molecule CSA_n Attachment cross section cm\²/molecule CSI_n Ionisation cross section cm\²/molecule --------------------------------------------------------------- !Wtable_end Cross sections are given for the temperature and pressure that was specified in the gas section (or that was default). For the conversion from cross section, given in cm\², to mean free path, one uses the relation (the constant is known as Loschmidt number): !W

  \λ = 1 / (L \× \σ)
  L = 2.6867775 \× 10\19\ molecules / cm\³
!W
Example 1: !W
  "-> &GAS"
  "-> &GAS -> magboltz" argon 80 co2 1 coll 20 e-field 20000 keep
  !"-> graphics -> options" log-x log-y
  Call "-> Call -> plot_frame"(0.01,1e-18,100,2e-15, ...
     `Electron energy [eV]`, ...
     `Cross section [cm2]`, ...
     `Cross section in argon 90 % CO2 20 %`)
  Call "-> Call -> plot_line"(e_1,cst_1,`"-> graphics -> REPRESENTATION -> item -> function-1"`)       // Total
  Call "-> Call -> plot_line"(e_1,cse_1,`"-> graphics -> REPRESENTATION -> item -> function-2"`)       // Elastic
  Call "-> Call -> plot_line"(e_1,csa_1,`"-> graphics -> REPRESENTATION -> item -> function-3"`)       // Attachment
  Call "-> Call -> plot_line"(e_1,csi_1,`"-> graphics -> REPRESENTATION -> item -> function-4"`)       // Ionisation
  Call "-> Call -> plot_end"
!W
This shows the various contributions to the cross section in an argon/CO\2\ mixture. Example 2: !W
  &GAS
  magboltz argon 100   co2   0   coll 20 e-field 200 keep
  magboltz argon  99.5 co2   0.5 coll 20 e-field 200 keep
  magboltz argon  99   co2   1   coll 20 e-field 200 keep
  magboltz argon  98   co2   2   coll 20 e-field 200 keep
  magboltz argon  95   co2   5   coll 20 e-field 200 keep
  magboltz argon  90   co2  10   coll 20 e-field 200 keep
  magboltz argon  50   co2  50   coll 20 e-field 200 keep
  magboltz argon   0   co2 100   coll 20 e-field 200 keep
  !"-> graphics -> options" lin-x lin-y
  Call "-> Call -> plot_frame"(0,0,6,1, ...
     `Electron energy [eV]`, ...
     `Energy distribution [normalised]`, ...
     `Electron energy in argon CO2 mixtures`)
  Call "-> Call -> plot_line"(e_1,f_1,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_line"(e_2,f_2,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
  Call "-> Call -> plot_line"(e_3,f_3,`"-> graphics -> REPRESENTATION -> item -> function-3"`)
  Call "-> Call -> plot_line"(e_4,f_4,`"-> graphics -> REPRESENTATION -> item -> function-4"`)
  Call "-> Call -> plot_line"(e_5,f_5,`"-> graphics -> REPRESENTATION -> item -> function-5"`)
  Call "-> Call -> plot_line"(e_6,f_6,`"-> graphics -> REPRESENTATION -> item -> function-6"`)
  Call "-> Call -> plot_line"(e_7,f_7,`"-> graphics -> REPRESENTATION -> item -> function-7"`)
  Call "-> Call -> plot_line"(e_8,f_8,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_end"
!W
This shows the dramatic modification of the electron energy distribution that occurs when one adds tiny amounts of CO\2\ to pure argon. [This option is not on by default.] 3 ANALYTIC-INTEGRATION Calls the analytic version of Magboltz, also known as Magboltz\ 1. This option, which is not default, is provided mainly for backwards compatibility, and only in Garfield up to version\ 8. Monte Carlo integration is currently believed to be superior for all gas mixtures. Analytic integration may still be the method of choice for a pure noble gas. Several anisotropic gases can not be used when analytic integration is requested. This option does not exist anymore in Garfield versions\ 9 and higher, which call Magboltz version\ 7 and higher. Magboltz version\ 7 can deal with pure noble gases - but it will be very slow. 4 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 "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA", this setting is overruled by the "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SWITCH" option. This option can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration. [Default: n=2, equivalent to SECOND-ORDER-TERMS.] 4 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 "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA" option which improves the accuracy of the Townsend coefficients. "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SWITCH" overrules this selection. HIGH-PRECISION is synonymous to SECOND-ORDER-TERMS. This option can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration, available only in Garfield version \  and earlier. [This is the default order, but is overruled by SWITCH.] 4 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 "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA" option which improves the accuracy of the Townsend coefficients. LOW-PRECISION is synonymous to FIRST-ORDER-TERMS. This option can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration, available only in Garfield version\ 7 and earlier. [The default is SECOND-ORDER-TERMS.] 4 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 option can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration, available only in Garfield version\ 7 and earlier. [This is not default.] 4 SWITCH The SWITCH option combines "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> ITERATE-ALPHA" and "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION -> SECOND-ORDER-TERMS" in the following way: If \α/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 can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration, available only in Garfield version\ 7 and earlier. [This option is default, \α/pressure is set to 50/pressure.] 4 diffusion Magboltz offers several ways of computing the diffusion: !Wul_start - The method from the textbook of Huxley and Crompton, for both the transverse and the longitudinal diffusion, either with the F0 or the H1 distribution functions. These formulae are only valid when the approximation that the longitudinal and transverse diffusion are equal is true. This is of course never true, but one can get a correction to the longitudinal diffusion from the ratio of the longitudinal to transverse diffusion without the magnetic field in the given gas at the E-field of interest. [from Steve Biagi] These diffusion coefficients are obtained when you specify F0-TRANSVERSE-DIFFUSION, H1-TRANSVERSE-DIFFUSION, F0-LONGITUDINAL-DIFFUSION and H1-LONGITUDINAL-DIFFUSION. The correction to the longitudinal diffusion is applied, using the G0 estimate of the longitudinal diffusion. F0-TRANSVERSE-DIFFUSION is default. - For the transverse diffusion, an alternative estimate based on the mean energy, computed with F0, is offered. - For the longitudinal diffusion, Magboltz computes on request a more accurate value using the so-called G0 functions. This is the default. !Wul_end These options can only be used with "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION" integration, available only in Garfield version\ 7 and earlier. 3 MONTE-CARLO-INTEGRATION Calls the Monte Carlo version of Magboltz. Magboltz used analytic integration in version\ 1 and it has used Monte Carlo integration from version\ 2 on. This technique, which is believed to be more accurate than analytic integration for nearly all gas mixtures, is default. Pure noble gases seem to be the only exception to this rule. Garfield up to version\ 8 maintained an interface to both the analytic integration method from Magboltz version\ 1 and the Monte Carlo method from Magboltz version\ 2. Garfield version\ 9 is interfaced only with Magboltz version\ 7, which uses Monte Carlo techniques, since the format of the gas descriptions used by this Magboltz version is no longer compatible with Magboltz version\ 1. [Monte Carlo integration is default.] 4 COLLISIONS Specifies the number of collisions, in multiplies of 1e7, to be used to compute the transport properties for each (E,B,angle) combination. This option can only be used with "-> &GAS -> MAGBOLTZ -> MONTE-CARLO-INTEGRATION" integration. Low values (e.g. 2-5) are suitable for mixtures than contain substantial amounts of quenchers. Nearly pure noble gases call for larger values (e.g. 10-20) while very large values (100 and more) are needed for pure noble gases. But in the latter case, it is preferable to use Magboltz\ 1 (see "-> &GAS -> MAGBOLTZ -> ANALYTIC-INTEGRATION"). The statistical accuracy of the drift velocity calculation improves with the square root of this parameter, while the CPU time consumption increases linearly. Since the accuracy depends on the gas mixture and on the field, it may be worthwhile in critical applications to estimate the statistical error of the Magboltz calculations for a given gas and a given field by repeatedly calculating the transport parameters: !W
  Call "-> Call -> book_histogram"(vhist,50)
  Call "-> Call -> book_histogram"(dlhist,50)
  Call "-> Call -> book_histogram"(dthist,50)
  Global nrndm=200
  For irndm From 1 To nrndm Do
     Say "Iteration {irndm}/{nrndm}"
     &GAS
     magboltz argon 90 methane 10 coll 5 e-field 125

     &MAIN
     Call "-> Call -> drift_velocity"(125,0,0,v)
     Call "-> Call -> fill_histogram"(vhist,v)
     Call "-> Call -> transverse_diffusion"(125,0,0,dt)
     Call "-> Call -> fill_histogram"(dthist,10000*dt)
     Call "-> Call -> longitudinal_diffusion"(125,0,0,dl)
     Call "-> Call -> fill_histogram"(dlhist,10000*dl)
  Enddo

  Call "-> Call -> plot_histogram"(vhist,`vD [cm/microsec]`,`Drift velocity`)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_histogram"(dthist,`σT [micron for 1 cm]`, ...
     `Transverse diffusion`)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_histogram"(dlhist,`σL [micron for 1 cm]`, ...
     `Longitudinal diffusion`)
  Call "-> Call -> plot_end"
!W
From the histograms, one concludes that, for argon 90\ % methane 10\ % and E=125\ V/cm, COLLISION=5 leads to a statistical error of 0.4\ % on the drift velocity, 4.5\ % on the transverse diffusion and 7\ % on the longitudinal diffusion. [By default: 10\ \×\ 960.000 collisions.] 3 MOBILITY Magboltz only computes the electron transport properties, not the ion transport properties. 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. "-> &GAS -> 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 cm\²/\μsec.V. [By default: no mobility.] 3 PRINT The original Magboltz output is shown when this option has been switched on. This output contains amongst others the ionisation, attachment and excitation rates which are needed if one wishes to correct the Townsend coefficients for Penning transfers. One also finds there the energy distribution. This output tends to be long and it may therefore be advisable to write it to a file: !W
  &GAS
  pressure 3 bar
  temperature 25 C
  > magboltz.rates
  magboltz argon 90 co2 10 ...
     e-field 100 200 500 1000 2000 5000 10000 20000 50000 100000 ...
     coll 3 ...
     print
  >
!W
[By default, this option is switched off.] 2 MATERIAL An interface to Heed which caters for solid materials - use the "-> &GAS -> HEED" command if your chamber is filled with gas. The MATERIAL command takes a chemical composition as argument, Format: !W
  MATERIAL  [ALUMINIUM "-> &GAS -> MATERIAL -> n"]    [ARGON n]     [CARBON n] ...
            [FLUORINE n]     [HELIUM n]    [HYDROGEN n] ...
            [KRYPTON n]      [LITHIUM n]   [NEON n] ...
            [NITROGEN n]     [OXYGEN n]    [SILICON n] ...
            [SULPHUR n]      [XENON n] ...
            DENSITY "-> &GAS -> MATERIAL -> density" ...
            WORK "-> &GAS -> MATERIAL -> work" ...
            [FANO "-> &GAS -> MATERIAL -> fano"]
!W
Example: !W
  material C 12 H 22 O 11 density 1.59 work 3
!W
Which would fill your device with sucrose, ordinary sugar. 3 n Number of atoms per molecule of the substance that fills the chamber. This number is mandatory, if you fill your chamber with pure silicon, for instance, you have to specify: !W
  material Si 1 density 2.3 work 3.6
!W
[No default] 3 density The density in g/cm\³ of the material. [Mandatory parameter, no default.] 3 work The work in eV needed to create an electron/ion(hole) pair. [Mandatory parameter, no default.] 3 fano The Fano parameter for the material. [By default set to 0.19.] 2 MERGE Merges the data from a gas file with the current gas data. This only works if the current data and the data in the file have at least 2 of the following 3 axes in common: the set of electric field values, the set of angles between E and B and the set of magnetic field values. This condition is trivially met if the current gas data and the data in the file both concern a zero magnetic field situation. If precisely 2 of the 3 axes coincide, then the merged data will contain only the transport properties which are found in both the current data and in the file. If all 3 axes coincide, then the merged data will contain all the transport properties that are found in either the current data or the file. Also the "-> &GAS -> ADD" command adds transport properties to the gas tables, under somewhat different conditions. Contrary to the "-> &GAS -> GET" command, MERGE can not read files written in earlier formats. The way out consists in reading old-format files with GET, writing them out using "-> &GAS -> WRITE" and then using the file thus obtained for the merge. Format: !W
  MERGE "-> &GAS -> MERGE -> file" ["-> &GAS -> MERGE -> member"]  [KEEP-OLD | REPLACE-OLD]
!W
Example: !W
  "-> &GAS -> get" "low.gas"
  merge "high.gas"
!W
3 file The name of the "-> dataset -> structure -> file" that contains the gas description that you wish to merge with the existing data. 3 member The name of the "-> dataset -> structure -> member" that you wish to merge with the existing data. 3 KEEP-OLD In case a transport property for a given (E, angle, B) combination, a cluster description or other element of the gas description is found in both the existing data and in the file, then the value from the existing data will be kept. [This is default.] 3 REPLACE-OLD In case a transport property for a given (E, angle, B) combination, a cluster description or other element of the gas description is found in both the existing data and in the file, then the value from the file will be used. [Default is to keep the existing data.] 2 MIX Computes the drift velocity and diffusion for a mixture of gases. The calculations are based on the work of G. Schultz and J. Gresser [NIM 151 (1978) 413-431] and use parametrised elastic 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 electrodes. 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 "-> &GAS -> MAGBOLTZ" program of Steve Biagi which is far superior in accuracy to this instruction. Format: !W
  MIX [ ARGON  "-> &GAS -> MIX -> 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 "-> &GAS -> MIX -> emin" ] ...
      [ MAXIMUM-ENERGY "-> &GAS -> MIX -> emax" ] ...
      [ STEPSIZE-ENERGY "-> &GAS -> MIX -> estep" ] ...

      [ CRITICAL-F0-FRACTION "-> &GAS -> MIX -> frcrit" ] ...
   
      [ "-> &GAS -> MIX -> E/P-RANGE" epmin epmax ] ...
      [ "-> &GAS -> MIX -> N-E/P" n ] ...
      [ LINEAR-E/P-SCALE | LOGARITHMIC-E/P-SCALE ] ...
   
      [ "-> &GAS -> MIX -> PLOT-F0" | NOPLOT-F0 ] ...
      [ "-> &GAS -> MIX -> PLOT-ENERGY-LOSS" | NOPLOT-ENERGY-LOSS ] ...
      [ "-> &GAS -> MIX -> PLOT-CROSS-SECTION" | NOPLOT-CROSS-SECTION ] ...
      [ "-> &GAS -> MIX -> PLOT-PATH" | NOPLOT-PATH ] ...
 
      [ "-> &GAS -> MIX -> PRINT-TABLES" | NOPRINT-TABLES ] ...

      [ "-> &GAS -> MIX -> MOBILITY" mob ] ...
      [ "-> &GAS -> MIX -> TOWNSEND-COEFFICIENT" \α/p ] ...
      [ "-> &GAS -> MIX -> ATTACHMENT-COEFFICIENT" \η/p ]
!W
Example: !W
  mix argon 50 ethane 50
!W
The gas in your chamber will be 50\ % argon and 50\ % ethane. 3 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.] 3 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.] 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.] 3 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.] 3 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. Also the energy distribution plot (see "-> &GAS -> MIX -> PLOT-F0") shows whether ionisation and excitation phenomena are likely to play a role. [By default 0.01.] 3 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.] 3 N-E/P Number of points in the drift velocity and diffusion tables. [By default 20.] 3 scale Selects whether the spacing of the E/p points should be linear or logarithmic. [Logarithmic by default.] 3 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" if ionisation and excitation are not expected to be a problem, and using representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" if a fraction "-> &GAS -> MIX -> frcrit" or more of the energy distribution exceeds the first ionisation or excitation threshold. [This plot is made by default.] 3 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". [This plot is by default not made.] 3 PLOT-CROSS-SECTION Requests a plot of the elastic electron scattering cross section. The curve is plotted using polyline representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". [This plot is made by default.] 3 PLOT-PATH Requests a plot of the mean free path of electrons in the gas. The curve is plotted using polyline representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". [This plot is by default not made.] 3 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.] 3 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. "-> &GAS -> ADD" provides similar functionality, and caters in addition for mobilities that are available in tabular form. The Garfield unit for mobility is cm\²/V.\μsec. [By default: no mobility.] 3 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. "-> &GAS -> 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 "-> &GAS -> MAGBOLTZ" can be used to compute Townsend coefficients. The Townsend coefficient should be entered as \α/pressure, with \α in units 1/cm and the pressure in Torr. [By default: no Townsend coefficient.] 3 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. "-> &GAS -> 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 "-> &GAS -> MAGBOLTZ" can be used to compute attachment coefficients. The attachment coefficient should be entered as \η/pressure, with eta in units 1/cm and the pressure in Torr. [By default: no attachment coefficient.] 2 OPTIONS Selects gas related as well as top level "-> OPTIONS". Format: !W
  OPTIONS [NOGAS-PLOT | "-> &GAS -> OPTIONS -> GAS-PLOT"] ...
          [NOGAS-PRINT | "-> &GAS -> OPTIONS -> GAS-PRINT"]
!W
Examples: !W
  "-> &GAS -> plot-options" drift-velocity nodiffusion notownsend
  opt gas-plot nogas-print
!W
Requests a plot of the drift velocity. If cluster data has been entered, then also a cluster plot will be made (this is default) but diffusion and multiplication graphs are not shown. Using further "-> &GAS -> PLOT-OPTIONS" options, one could have fixed for instance the scale of the drift velocity plot. !W
  &GAS
  magboltz argon 70 dme 30
  opt gas-print nogas-plot
  >ArDME.print
  &MAIN
  >
!W
"-> &GAS -> MAGBOLTZ" is called to compute transport properties for a 70/30 mixture of argon and DME. The transport tables are printed when leaving the section - note the use of the "-> &MAIN" command to close the gas section. They do not appear on the screen, but are "-> output" to the file ArDME.print. 3 GAS-PLOT Switching on this option requests plots of the drift velocity, the ion mobility, the diffusion coefficients, the Lorentz angle, the Townsend coefficient, the attachment coefficient, the ion dissociation coefficient, and of the excitation and ionisation rates to be produced. If "-> &GAS -> SRIM" data has been entered, then in addition the energy loss, range and straggling parameters are plotted. These plots are made when the gas section is left, not when the option is switched on. Use e.g. "-> &MAIN" to close the section. Once outside the gas section, the plots can be obtained by entering the "-> &OPTIMISE" section and issued a "-> &OPTIMISE -> PLOT-GAS" command. The representations used in the graphs are the following: !Wul_start - Drift velocity: In the absence of a magnetic field, only the drift velocity is shown, using polyline representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". If the magnetic field is not zero, then the component parallel with E uses "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the component parallel with the orthogonal part of B uses "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" while the component parallel with E\×B is shown using "-> graphics -> REPRESENTATION -> item -> FUNCTION-3". - Ion mobility: The ion mobility curve is drawn with "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". - Diffusion: The longitudinal diffusion uses "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" while the transverse diffusion uses "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". - Multiplication: The Townsend coefficient is drawn with "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the attachment coefficient is shown using "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" and the ion dissociation coefficient is shown using "-> graphics -> REPRESENTATION -> item -> FUNCTION-3". - Cluster size: the cluster size distribution is drawn with "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". - SRIM: the SRIM total energy loss is shown with "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the electromagnetic energy loss with "-> graphics -> REPRESENTATION -> item -> FUNCTION-2", and the nuclear energy loss with "-> graphics -> REPRESENTATION -> item -> FUNCTION-3". - SRIM: the SRIM projected range uses "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the longitudinal straggling "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" and the transverse straggling "-> graphics -> REPRESENTATION -> item -> FUNCTION-3". - Excitation and ionisation: the excitation rates use "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" and the ionisation rates use "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". !Wul_end [These graphs are not made by default.] With the "-> &GAS -> 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. Use the "-> Call -> ATTACHMENT", "-> Call -> DRIFT_VELOCITY", "-> Call -> GET_E/P_TABLE", "-> Call -> ION_MOBILITY", "-> Call -> LONGITUDINAL_DIFFUSION", "-> Call -> LORENTZ_ANGLE", "-> Call -> TOWNSEND", "-> Call -> TRANSVERSE_DIFFUSION", "-> Call -> VELOCITY_E", "-> Call -> VELOCITY_BTRANSVERSE", "-> Call -> VELOCITY_ExB", "-> Call -> EXCITATION_RATE" and "-> Call -> IONISATION_RATE" procedures for fully customised plots. [This option is off initially, its setting is remembered from one gas section to the next.] 3 GAS-PRINT This option is responsible for making a printout of all available information on the gas. The tables are printed when the gas section is being left, not when the option is switched on. Use e.g. "-> &MAIN" to close the section. As a consequence, if you wish to "-> output" the tables to a file, then you have to start the re-routing just before leaving the section and revert to normal output once you are in the next section: Once outside the gas section, this table can be obtained by entering the "-> &OPTIMISE" section and issued a "-> &OPTIMISE -> PRINT-GAS" command. !W
  &GAS
  magboltz argon 80 co2 20
  opt gas-print
  > Ar_80_CO2_20.print
  &MAIN
  >
!W
The output can not be used directly as input to the program, use the "-> &GAS -> WRITE" instruction for that purpose. [This option is off initially, its setting is remembered from one gas section to the next.] 2 PARAMETERS Various parameters of the gas, such as the number of clusters per cm, can be entered with this command. Originally, most of this data was only used for a simple Landau-based backup estimate of the cluster size distribution if the "-> &GAS -> CLUSTER" size distribution is not known from data and if the "-> &GAS -> HEED" model can not be used. Some of the parameters are however used for other purposes too: !Wul_start - The mean number of clusters is used if the clustering model you plan to choose with the "-> &DRIFT -> TRACK" command, is based on the cluster size distribution entered with "-> &GAS -> CLUSTER". - The number of nucleons in an atom and the nuclear charge (A and Z) is used also by the "-> &DRIFT -> TRACK -> SRIM" clustering model. - The ion diffusion coefficients are used when performing MC drift of ions. !Wul_end Format: !W
  PARAMETERS [ "-> &GAS -> PARAMETERS -> A" a ] ...
             [ "-> &GAS -> PARAMETERS -> Z" z ] ...
             [ "-> &GAS -> PARAMETERS -> RHO" density ] ...
             [ "-> &GAS -> PARAMETERS -> E-PAIR" epair ] ...
             [ "-> &GAS -> PARAMETERS -> E-MOST-PROBABLE" emprob ] ...
             [ "-> &GAS -> PARAMETERS -> MEAN" mean_number_of_clusters ] ...
             [ TRANSVERSE-ION-DIFFUSION {"-> &GAS -> PARAMETERS -> THERMAL" | "-> &GAS -> PARAMETERS -> sigma"_T} ] ...
             [ LONGITUDINAL-ION-DIFFUSION {THERMAL | sigma_L} ]
!W
As shown in the format description, several lines may be used although a single line is perfectly acceptable as well. Example: !W
  PARA MEAN 20
!W
This format could be used if you wish to compute arrival time spectra and enter the cluster size distribution with CLUSTER. 3 A The number of nucleons per gas molecule. This parameter is used by (and mandatory for): !Wul_start - the "-> &DRIFT -> TRACK -> SRIM" clustering model; - the Landau model which is used to compute the cluster size distribution if you didn't enter such a distribution yourself with "-> &GAS -> CLUSTER" nor asked "-> &GAS -> HEED" to simulate the ionisation process. !Wul_end 3 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 "-> &GAS -> CLUSTER" nor asked "-> &GAS -> HEED" to simulate the ionisation process. You may also type MOST-PROBABLE-ENERGY-LOSS. 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 "-> &GAS -> CLUSTER" nor asked "-> &GAS -> HEED" to simulate the ionisation process. You may also type PAIR-CREATION-ENERGY. 3 MEAN The average number of clusters per cm. This parameter is not used when clustering is performed according to the "-> &DRIFT -> TRACK -> HEED" model, but it is required for the "-> &DRIFT -> TRACK -> EXPONENTIAL-SPACING" and "-> &DRIFT -> TRACK -> EQUAL-SPACING" clustering models. In the latter 2 cases, the parameter is required even if a cluster size distribution has been entered with a "-> &GAS -> CLUSTER" statement. You may also type N-MEAN. [No default setting.] 3 RHO The density of the gas in g/cm\³. This parameter is used by: !Wul_start - the "-> &DRIFT -> TRACK -> SRIM" clustering model; - the simple Landau model which is used to compute the cluster size distribution if you didn't enter such a distribution yourself with "-> &GAS -> CLUSTER" nor asked "-> &GAS -> HEED" to simulate the ionisation process. !Wul_end SRIM files contain a density estimate and, when reading such a file with the "-> &GAS -> SRIM" command in the gas section, the gas density will be overwritten. It is therefore advisable to issue the PARAMETERS command after the SRIM command if you know the gas density. 3 Z The nuclear charge of the gas molecules. This parameter is used by (and mandatory for): !Wul_start - the "-> &DRIFT -> TRACK -> SRIM" clustering model; - the Landau model which is used to compute the cluster size distribution if you didn't enter such a distribution yourself with "-> &GAS -> CLUSTER" nor asked "-> &GAS -> HEED" to simulate the ionisation process. !Wul_end 3 THERMAL Requests thermal diffusion be applied when drifting ions. The thermal diffusion coefficients are computed using the expression: !W
           .------
          / 2 k\B\ T
  \σ = \\  /  ------
       \\/    q\e\ E
!W
Where !Wul_start - k\B\ = Boltzmann constant, 1.38... 10\-23\ J/K, - T = "-> &GAS -> temperature" of the gas [K], - q\e\ = charge of the electron, 1.6... 10\-19\ C, - E = local electric field [V/cm] !Wul_end !W [By default, the diffusion is set to 0.] 3 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 "-> &DRIFT -> methods -> 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.] 2 PLOT-OPTIONS Selects the plots to be made in response to the "-> &GAS -> OPTIONS -> 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 "-> Call -> DRIFT_VELOCITY" and related procedures to have full control over the presentation of the plot. Format: !W
  PLOT-OPTIONS ["-> &GAS -> PLOT-OPTIONS -> plot" ["-> &GAS -> PLOT-OPTIONS -> options"]] ...
!W
Example: !W
  plot-options drift lin-x log-y nodiff nocluster
!W
(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.) 3 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: !Wtable_start !T+P + . ----------------------------------------------------------------- Plot Contains ----------------------------------------------------------------- ATTACHMENT-COEFFICIENT-PLOT Synonym for TOWNSEND-COEFFICIENT-PLOT CLUSTER-SIZE-PLOT Cluster size distribution DIFFUSION-COEFFICIENTS-PLOT Transverse + longitudinal diffusion DRIFT-VELOCITY-PLOT Drift velocity of electrons EXCITATION-RATES-PLOT Excitation and ionisation rates ION-MOBILITY-PLOT Ion mobility IONISATION-RATES-PLOT Synonym for EXCITATION-RATES-PLOT LORENTZ-ANGLES-PLOT Lorentz angles for electrons MOBILITY-PLOT Synonym for ION-MOBILITY-PLOT TOWNSEND-COEFFICIENT-PLOT Townsend and attachment coefficients SRIM-PLOTS SRIM energy loss and straggling ----------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. The transverse and the longitudinal diffusion are shown together in a single graph. To suppress one of them but not the other requires a "-> &GAS -> RESET" of the item that is not desired. The same applies to the Townsend and attachment coefficients, and to the ionisation and excitation rates. 2. One may use ATTACHMENT-COEFFICIENT-PLOT as synonym for TOWNSEND-COEFFICIENT-PLOT. 3. For SRIM plots, the "-> &GAS -> PLOT-OPTIONS -> options" are not honoured. !Wol_end 3 options The plot can be followed by one or more of the following options: !Wtable_start !T+P + . ---------------------------------------------------------------- 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 ---------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. The transverse and longitudinal diffusion coefficients, the Townsend and attachment coefficients, as well as the ionisation and excitation rates, are plotted in one graph and have therefore a common set of axes. 2. RANGE does not apply to the cluster size distribution. 3. These options do not apply for the SRIM plots. !Wol_end 2 PRESSURE Sets the pressure of the gas. The pressure is used by the gas mixing instructions "-> &GAS -> MIX" and "-> &GAS -> MAGBOLTZ" as well as by "-> &GAS -> 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 "-> &GAS -> TABLE -> scaling" laws. Format: !W
  PRESSURE "-> &GAS -> PRESSURE -> pressure" ["-> &GAS -> PRESSURE -> unit"]
!W
Example: !W
  pressure 2 bar
!W
3 pressure The pressure of the gas. [Initially set to 760\ Torr.] 3 unit Specifies the unit by which you enter the gas pressure. Garfield internally stores the pressure in Torr and e.g. the E/p tables are therefore in V/cm.Torr, no matter the pressure unit you used on input. Also the unit with which the pressure is displayed is not affected by the unit with which you enter it. The following pressure units are accepted: !Wtable_start !T+ + +P . ---------------------------------------------------------------- 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, hPa, kPa N/m2 101325 N/m\² N/M2 bar 1.01325 bar BAR mbar 1013.25 hPa MBAR, MILLI-BAR ---------------------------------------------------------------- !Wtable_end [The default pressure input unit is the Torr.] 2 REPLACE REPLACE is a synonym of "-> &GAS -> ADD". 2 RESET Performs a selective or global reset of the gas data. A selective reset is performed if any "-> &GAS -> RESET -> item"s are listed, otherwise all gas data is deleted. Format: !W
  RESET ["-> &GAS -> RESET -> item"1] [item2] ...
!W
3 item The following items can be reset: !Wdl_start !T+ + ---------------------------------------------------------------------- Item Description ---------------------------------------------------------------------- ATTACHMENT-COEFFICIENTS Resets the attachment coefficient and resets the interpolation and extrapolation methods for this item to their defaults. CLUSTERING-DATA Resets the cluster size distribution, whether derived from Heed, from a Landau distribution or from a table of cluster sizes. Also resets the mean number of clusters per cm as entered with the "-> &GAS -> PARAMETERS" statement. DIFFUSION Equivalent to LONGITUDINAL-DIFFUSION, TRANSVERSE-DIFFUSION and DIFFUSION-TENSOR combined. DIFFUSION-TENSOR Resets all 6 components of the diffusion covariance matrix and resets the interpolation and extrapolation methods for this item to their defaults. DRIFT-VELOCITY Resets all 3 drift velocity components, i.e. the component parallel with E, the component parallel with the part of B transverse with respect to E and the component parallel with E\×B. Also resets the interpolation and extrapolation methods for these items to their defaults. EXCITATION-RATES Resets all excitation rates and resets the the interpolation and extrapolation methods for this item to their defaults. GAS-IDENTIFIER Sets the gas identifier to a blank string. ION-DISSOCIATION Resets the ion dissociation coefficients and resets the interpolation and extrapolation methods for this item to their defaults. ION-MOBILITY Resets the ion mobility and resets the interpolation and extrapolation methods for this item to their defaults. IONISATION-RATES Resets all ionisation rates and resets the the interpolation and extrapolation methods for this item to their defaults. LONGITUDINAL-DIFFUSION Resets the longitudinal diffusion and resets the interpolation and extrapolation methods for this item to their defaults. LORENTZ-ANGLES Resets the Lorentz angles and resets the interpolation and extrapolation methods for this item to their defaults. TABLES Equivalent to combining ATTACHMENT-COEFFICIENTS, DIFFUSION, DRIFT-VELOCITY, LORENTZ-ANGLES and TOWNSEND-COEFFICIENTS, EXCITATION-RATES and IONISATION-RATES.. TOWNSEND-COEFFICIENTS Resets the Townsend coefficient and sets the interpolation and extrapolation methods for this item to their defaults. TRANSVERSE-DIFFUSION Resets the transverse diffusion and sets the interpolation and extrapolation methods for this item to their defaults. --------------------------------------------------------------------- !Wdl_end 2 SRIM Reads SRIM energy loss, range and straggling tables. The SRIM program, available from http://www.srim.org, simulates the stopping of ions by matter. Amongst other results, it produces a table of energy loss (electromagnetic and nuclear), the projected range and the straggling (longitudinal and transverse), as function of particle energy. These tables can serve as a basis to generate individual absorption patterns. In order to estimate electron deposition from the SRIM model, Garfield will need the "-> &GAS -> PARAMETERS -> A" and "-> &GAS -> PARAMETERS -> Z" of the gas to be entered with the "-> &GAS -> PARAMETERS" statement. The SRIM files do not seem to contain this information. SRIM files contain a density estimate and, when reading such a file, the gas density, if entered on beforehand with the "-> &GAS -> PARAMETERS" statement, would be overwritten. It is therefore advisable to issue the PARAMETERS command after the SRIM command if the density as estimated by SRIM is not considered reliable. Please note that the a density entered with the PARAMETERS statement will not affect the range estimated by SRIM. The energy loss, range and straggling parameters will be plotted, when the gas section is being left, if the "-> &GAS -> OPTIONS -> GAS-PLOT" option is switched on. The SRIM tables are included in the files that are written by the "-> &GAS -> WRITE" command and read by the "-> &GAS -> GET" command. Use the "-> &DRIFT -> TRACK -> SRIM" option of the "-> &DRIFT -> TRACK" command to produce clusters based on this model. Comments, and in particular comparisons with experimental data, as well as suggestions for improvement are invited. Format: !W
  SRIM FILE "-> &GAS -> SRIM -> file" ...
       WORK-FUNCTION "-> &GAS -> SRIM -> work" ...
       FANO-FACTOR "-> &GAS -> SRIM -> fano"
!W
Example: !W
  srim file="SRIMHeInCF.dat" work=40
!W
A file with SRIM output for \α particles traversing He/CF\4\ is read, and we assume a work function of 40\ eV. 3 file Name of the file which contains the SRIM table. The energy range of the table should at least extend up to the kinetic energy of the incoming particle, and should extend as far down as SRIM will allow so as to simulate the final absorption. The Garfield interface extrapolates to higher and lower energies by taking resp. the last and first tabulated values. The file for \α particles traversing a mixture of He and CF\4\ would look as follows: !W
   ==================================================================
                Calculation using SRIM-2003 
                SRIM version ---> SRIM-2003.26
                Calc. date   ---> October 24, 2005 
   ==================================================================

   Disk File Name = SRIM Outputs\\Helium in He- C- F

   Ion = Helium [2] , Mass = 4.003 amu

   Target Density =  1.9000E-03 g/cm3 = 1.1026E+20 atoms/cm3
   ======= Target  Composition ========
      Atom   Atom   Atomic    Mass     
      Name   Numb   Percent   Percent  
      ----   ----   -------   -------  
       He      2    053.12    020.49   
        C      6    009.38    010.86   
        F      9    037.50    068.65   
   ====================================
   Bragg Correction = 0.00%
   Stopping Units =  MeV / (mg/cm2) 
   See bottom of Table for other Stopping units 

     Ion        dE/dx      dE/dx     Projected  Longitudinal   Lateral
    Energy      Elec.      Nuclear     Range     Straggling   Straggling
  -----------  ---------- ---------- ----------  ----------  ----------
    10.00 keV   2.629E-01  6.037E-02  128.41 um    52.40 um    46.05 um  
    11.00 keV   2.760E-01  5.715E-02  140.80 um    55.57 um    49.42 um  
    12.00 keV   2.885E-01  5.431E-02  153.00 um    58.53 um    52.63 um  
  (...)
     7.00 MeV   5.985E-01  3.596E-04   39.51 mm     1.44 mm   790.64 um  
     8.00 MeV   5.416E-01  3.196E-04   48.75 mm     1.96 mm   931.02 um  
     9.00 MeV   5.000E-01  2.879E-04   58.85 mm     2.44 mm     1.09 mm  
    10.00 MeV   4.604E-01  2.622E-04   69.81 mm     2.91 mm     1.25 mm  
  -----------------------------------------------------------
   Multiply Stopping by        for Stopping Units
   -------------------        ------------------
    1.8999E-02                 eV / Angstrom 
    1.8999E-01                keV / micron   
    1.8999E-01                MeV / mm       
    1.0000E+00                keV / (ug/cm2) 
    1.0000E+00                MeV / (mg/cm2) 
    1.0000E+03                keV / (mg/cm2) 
    1.7231E+01                 eV / (1E15 atoms/cm2)
    1.5537E+00                L.S.S. reduced units
   ==================================================================
   (C) 1984,1989,1992,1998,2003 by J.P. Biersack and J.F. Ziegler
!W
Recipe to be provided ... Berta ! [No default; mandatory argument.] 3 work Asymptotic (i.e. high energy) electromagnetic energy loss needed to produce a single electron, expressed in eV. The work function depends on the gas and is typically a factor 2 larger than the ionisation energy. [No default; mandatory argument.] 3 fano Asymptotic (i.e. high energy) Fano factor for the production of electrons. The Fano factor equals the RMS\²/average of the number of electrons produced by a given amount of electromagnetic energy. The factor depends on the electromagnetic energy - it tends to decrease from 1 at threshold to the asymptotic value which needs to be specified. If set to NONE (or 0), the energy used for an electron will be equal to the "-> &GAS -> SRIM -> work" function, without fluctuations. [By default: 0.17.] 2 TABLE Enters the tables of electron transport properties and of the ion mobility, as function of the reduced electric field and, in case a magnetic field is present, also as function of the magnetic field strength and of the angle between E and B. Each of the table entries can either be tabulated or be computed from a parametrisation. In either case, the quantities that obey simple pressure "-> &GAS -> TABLE -> scaling" laws, have to be entered multiplied by the appropriate power of the pressure. 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 "-> &GAS -> 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 in the same sequence as in the table. The entry names should not be followed by parametrisations. The place of the E/p values in the table should be indicated by 'E/P'. There is no preferred order of the entries. If you opt for a parametrised form for one or more entries, then "-> &GAS -> TABLE -> function"s have to follow the names of the entries that are to be parametrised. The parametrisations that you enter are not stored as functions, rather they are evaluated at the E/p, angle(E,B) and B values of the table. The list thus obtained will be interpolated when transport properties are required, like for tabulated entries. If all entries are entered in a parametrised form, then you can either establish the list of E/p values by tabulating them or by specifying an "-> &GAS -> TABLE -> electric_field" range. You have the possibility to create tables with a dependence on the "-> &GAS -> TABLE -> angle" between E and B, as well as on the "-> &GAS -> TABLE -> magnetic_field", provided a magnetic field is present in the chamber. Format: !W
  TABLE [ "-> &GAS -> TABLE -> E/P" ] ... 
        [ "-> &GAS -> TABLE -> DRIFT-VELOCITY" [ "-> &GAS -> TABLE -> function" ] ] ...
        [ "-> &GAS -> TABLE -> BTRANSVERSE-VELOCITY" [ function ] ] ...
        [ "-> &GAS -> TABLE -> ExB-VELOCITY" [ function ] ] ...
        [ "-> &GAS -> TABLE -> ION-MOBILITY" [ function ] ] ...
        [ "-> &GAS -> TABLE -> ION-DISSOCIATION-COEFFICIENT" [ function ] ] ...
        [ "-> &GAS -> TABLE -> LORENTZ-ANGLE" [ function ] ] ...
        [ "-> &GAS -> TABLE -> LONGITUDINAL-DIFFUSION-COEFFICIENT" [ function ] ] ...
        [ "-> &GAS -> TABLE -> TRANSVERSE-DIFFUSION-COEFFICIENT" [ function ] ] ...
        [ "-> &GAS -> TABLE -> TOWNSEND-COEFFICIENT" [ function ] ] ...
        [ "-> &GAS -> TABLE -> ATTACHMENT-COEFFICIENT" [ function ] ] ...
        [ "-> &GAS -> TABLE -> DUMMY" [ function ] ] ...
        [ "-> &GAS -> TABLE -> E/P-RANGE" epmin epmax ] [ "-> &GAS -> TABLE -> N-E/P" nep ] ...
          [ "-> &GAS -> TABLE -> LOGARITHMIC-E/P-SCALE" | "-> &GAS -> TABLE -> LINEAR-E/P-SCALE" ] ...
        [ [ "-> &GAS -> TABLE -> B-RANGE" bmin bmax ] [ "-> &GAS -> TABLE -> N-B" nb ] | ...
          [ "-> &GAS -> TABLE -> B-FIELD" b ] ] ...
        [ [ "-> &GAS -> TABLE -> ANGLE-RANGE" amin amax ]  [ "-> &GAS -> TABLE -> N-ANGLE" nangle ] | ...
          [ "-> &GAS -> TABLE -> ANGLE" angle ] ]
!W
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: !W
  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

  // Note that the preceding line is intentionally left blank
!W
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. 3 E/P Indicates where the E/p values are located in the listing that follows the command. The keyword is not followed by a function. This is an optional keyword. If the E/P keyword is not used, then all transport properties must be specified by means of functions. 3 ATTACHMENT-COEFFICIENT If not followed by a function, the keyword indicates the location of the attachment coefficients for electrons in the listing that follows the command. The attachment coefficients are computed from the function if the keyword is followed by a function. The coefficients should not be part of the listing in this case. With a view to pressure "-> &GAS -> TABLE -> scaling", one should in either case enter the attachment coefficients divided by the pressure. The quantity to be entered thus has the unit of 1/(cm.Torr). Access to the data is provided with the "-> Call -> ATTACHMENT" procedure. [Entering attachment coefficients is optional.] 3 BTRANSVERSE-VELOCITY If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the component of the electron velocity parallel with the part of B that is transverse with respect to E. This velocity component is computed from the function if the keyword is followed by a function. The velocity component should not be part of the listing in this case. In either case, one should enter the velocity component in units of cm/\μsec. This component should only be included in the table if a magnetic field has been defined. Although you do not have to enter this component if a magnetic field has been defined, you're strongly advised to do so if you dispose of the relevant data. If the component has not been entered, but is needed for a calculation, then the missing "-> &DRIFT -> methods -> velocity" components will be computed using the Lorentz angle, if available, otherwise from the Langevin equation. Access to the data is provided with the "-> Call -> VELOCITY_BTRANSVERSE" procedure. [Entering this component of the velocity is optional.] 3 DRIFT-VELOCITY Enters the drift "-> &DRIFT -> methods -> velocity". The precise quantity to be entered depends on the presence or not of a magnetic field: !Wul_start - In case a magnetic field is present: If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the component of the electron velocity parallel with E. If you do not enter both the component parallel with E\×B and the component parallel with the part of B that is transverse with respect to E, then you should enter here the norm of the drift velocity. A function following this keyword should return the quantity described above. There should not be a corresponding item in the table if a function is specified. - In case there is no magnetic field: If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the norm of the electron drift velocity. The velocity is computed from the function if the keyword is followed by a function. The velocity should not be part of the listing in this case. The other components of the electron velocity vector should not be entered if there is no magnetic field. !Wul_end In all cases, one should enter the velocity (component) in units of cm/\μsec. The magnitude of the drift velocity can be accessed through the "-> Call -> DRIFT_VELOCITY" procedure. To obtain only the part parallel with E, one uses "-> Call -> VELOCITY_E". [Although entering the drift velocity is optional, one would normally do so since very few calculations can be performed if velocity data is absent.] 3 ExB-VELOCITY If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the component of the electron velocity parallel with E\×B. This velocity component is computed from the function if the keyword is followed by a function. The velocity component should not be part of the listing in this case. In either case, one should enter the velocity component in units of cm/\μsec. This component should only be included in the table if a magnetic field has been defined. Although you do not have to enter this component if a magnetic field has been defined, you're strongly advised to do so if you dispose of the relevant data. If the component has not been entered, but is needed for a calculation, then the missing "-> &DRIFT -> methods -> velocity" components will be computed using the Lorentz angle, if available, otherwise from the Langevin equation. Access to the data is provided with the "-> Call -> VELOCITY_ExB" procedure. [Entering this component of the velocity is optional.] 3 ION-DISSOCIATION-COEFFICIENT If not followed by a function, the keyword indicates the location of the dissociation coefficients for (negative) ions in the listing that follows the command. The dissociation coefficients are computed from the function if the keyword is followed by a function. The coefficients should not be part of the listing in this case. With a view to pressure "-> &GAS -> TABLE -> scaling", one should in either case enter the dissociation coefficients divided by the pressure. The quantity to be entered thus has the unit of 1/(cm.Torr). Access to the data is provided with the "-> Call -> ION_DISSOCIATION" procedure. [Entering dissociation coefficients is optional.] 3 ION-MOBILITY If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the ion mobility. The ion mobility is computed from the function if the keyword is followed by a function. The ion mobility should not be part of the listing in this case. In either case, one should enter the ion mobility in units of cm\²/(\μsec.V). Access to the data is provided with the "-> Call -> ION_MOBILITY" procedure. [Entering the ion mobility is optional.] 3 LONGITUDINAL-DIFFUSION-COEFFICIENT If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the longitudinal diffusion coefficient for electrons. The longitudinal diffusion coefficients are computed from the function if the keyword is followed by a function. The longitudinal diffusion coefficients should not be part of the listing in this case. With a view to pressure "-> &GAS -> TABLE -> scaling", one should in either case enter the amount of longitudinal diffusion over 1\ cm of drift, multiplied with the square root of the pressure. This quantity has the unit of \√(cm.Torr). Access to the data is provided with the "-> Call -> LONGITUDINAL_DIFFUSION" procedure. [Entering the longitudinal diffusion is optional.] 3 LORENTZ-ANGLE If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the Lorentz angle for electrons. This is the angle between the electric field and the drift velocity vector provided E and B are perpendicular. The Lorentz angle is computed from the function if the keyword is followed by a function. The Lorentz angle should not be part of the listing in this case. In either case, the Lorentz angle should be entered in degrees. This component can only be included in the table if a magnetic field has been defined. If you have included all 3\ components of the drift velocity vector, then you do not have to enter the Lorentz angle since this information will not be used. If however you enter only the velocity component parallel with E, then you're strongly advised to tabulate the Lorentz angle if you dispose of the relevant data. If neither Lorentz angles nor transverse velocity components are available, then the "-> &DRIFT -> methods -> velocity" vector will be computed using the Langevin equation. Access to the data is provided with the "-> Call -> LORENTZ_ANGLE" procedure. [Entering Lorentz angles is is optional.] 3 TOWNSEND-COEFFICIENT If not followed by a function, the keyword indicates the location of the Townsend coefficients for electrons in the listing that follows the command. The Townsend coefficients are computed from the function if the keyword is followed by a function. The coefficients should not be part of the listing in this case. With a view to pressure "-> &GAS -> TABLE -> scaling", one should in either case enter the Townsend coefficient divided by the pressure. The quantity to be entered thus has the unit of 1/(cm.Torr). Access to the data is provided with the "-> Call -> TOWNSEND" procedure. [Entering Townsend coefficients is optional.] 3 TRANSVERSE-DIFFUSION-COEFFICIENT If not followed by a function, the keyword indicates the location, in the listing that follows the command, of the transverse diffusion coefficient for electrons. The transverse diffusion coefficients are computed from the function if the keyword is followed by a function. The transverse diffusion coefficients should not be part of the listing in this case. The "-> &GAS -> methods -> coordinate_system" aligns the longitudinal diffusion with the electric field, not necessarily with the drift velocity vector. The transverse diffusion is the average of the diffusion perpendicular to E. With a view to pressure "-> &GAS -> TABLE -> scaling", one should in either case enter the amount of transverse diffusion over 1\ cm of drift, multiplied with the square root of the pressure. This quantity has the unit of \√(cm.Torr). Access to the data is provided with the "-> Call -> TRANSVERSE_DIFFUSION" procedure. [Entering the transverse diffusion is optional.] 3 function Entries which are given in the form of a parametrisation, may depend on the following variables: !Wtable_start !T+P + + . -------------------------------------------------------------------- Variable Meaning Value, Unit -------------------------------------------------------------------- ANGLE_EB Angle between E and B degrees B Magnetic field Tesla BOLTZMANN Boltzmann constant 1.380658 10\-23\ J/K ECHARGE Electron charge 1.60217733 10\-19\ C EP E/p V/cm.Torr P Pressure Torr T Temperature K -------------------------------------------------------------------- !Wtable_end The magnetic field related quantities, ANGLE_EB and B, are to be used only when there is a magnetic field. Example: See the "-> Call -> FIT_EXPONENTIAL" procedure. 3 scaling The simple scaling laws used by Garfield to extrapolate to a different pressure are listed in the table below. When using "-> &GAS -> MAGBOLTZ" or "-> &GAS -> 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. !Wtable_start !T+ + + . --------------------------------------------------------------------- quantity scaling enter --------------------------------------------------------------------- drift velocity v vs E/p v ion mobility \μ vs E/p \&mu diffusion coefficients \σ.\√p vs E/p \σ.\√p Townsend coefficient \α/p vs E/p \α/p Attachment coefficient \η/p vs E/p \η/p Lorentz angles - angle --------------------------------------------------------------------- !Wtable_end Example: the diffusion coefficient varies approximately with pressure according to the formula: !W
  \σ(p=p1) = \σ(p=p0) \√p0/\√p1
!W
hence \σ.\√p is approximately constant. 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: !W
  table e/p trans-diff long-diff
        1   0.1        0.1
        2   0.1        0.2
        3   0.1        0.3
!W
Not assigning the transverse diffusion: !W
  table e/p dummy long-diff
        1   0.1   0.1
        2   0.1   0.2 
        3   0.1   0.3
!W
Alternatively, you could have kept the original table followed by a "-> &GAS -> RESET" TRANS-DIFF command. 3 E/P-RANGE See "-> &GAS -> TABLE -> electric_field". 3 N-E/P See "-> &GAS -> TABLE -> electric_field". 3 LOGARITHMIC-E/P-SCALE See "-> &GAS -> TABLE -> electric_field". 3 LINEAR-E/P-SCALE See "-> &GAS -> TABLE -> electric_field". 3 electric_field 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 the table is composed exclusively of computed entries. There is in that case no E/P keyword on the TABLE instruction line. You may specify that you wish linearly or logarithmically spaced points, and you may also select the number of points. [By default: 100 to 100000\ V/cm in 20 logarithmic steps.] 3 ANGLE-RANGE See "-> &GAS -> TABLE -> angle". 3 N-ANGLE See "-> &GAS -> TABLE -> angle". 3 ANGLE See "-> &GAS -> TABLE -> angle". 3 angle Sets the range of angles between E and B to be covered by the table or the angle between E and B for which the table is meant to be used. Specifying such a range is valid only if there is a magnetic field. Even though specifying an angle range is useful mainly if you have at least one computed table entry which depends on the angle, you may also specify the range for a tabulated table. Doing this forces the table to have room for B or angle dependent entries, which you can later add with the "-> &GAS -> ADD" command. For defaults and further considerations, see the choice of "-> &GAS -> MAGBOLTZ -> ANGLE" for the MAGBOLTZ command. 3 B-RANGE See "-> &GAS -> TABLE -> magnetic_field". 3 N-B See "-> &GAS -> TABLE -> magnetic_field". 3 B-FIELD See "-> &GAS -> TABLE -> magnetic_field". 3 magnetic_field Sets the range of magnetic field strengths to be covered by the table or the magnetic field strength for which the table is meant to be used. Specifying such a range is valid only if there is a magnetic field. Even though specifying an magnetic field is useful mainly if you have at least one computed table entry which depends on this field, you may also specify the range for a tabulated table. Doing this forces the table to have room for B or angle dependent entries, which you can later add with the "-> &GAS -> ADD" command. For defaults and further considerations, see the choice of "-> &GAS -> MAGBOLTZ -> B-FIELD" for the MAGBOLTZ command. 2 TEMPERATURE Sets the temperature of the gas. The temperature is used by the gas mixing instructions ("-> &GAS -> MIX" and "-> &GAS -> MAGBOLTZ") and also by "-> &GAS -> 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 "-> &GAS -> TABLE -> scaling" of the transport properties but does not apply temperature scaling laws. Format: !W
  TEMPERATURE "-> &GAS -> TEMPERATURE -> temp" ["-> &GAS -> TEMPERATURE -> unit"]
!W
Example: !W
  TEMPERATURE 300 K
!W
For room temperature. 3 temp The temperature of the gas. [Initially set to 300\ K.] 3 unit The unit with which you enter the temperature. Garfield internally stores the pressure in Kelvin. Temperatures are output in K or in C, the unit which is chosen for output doesn't depend on the unit you use for input. Various temperature units are recognised, as listed in the table: !Wtable_start !T+ + +P . ------------------------------------------------------------------- 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 Réaumur (T-273.15)*4/5 REAUMUR, RE ------------------------------------------------------------------- !Wtable_end [Default input unit is Kelvin.] 2 TRIM Reads an event generated by the TRIM program. Interface written by James Butterworth. Format: !W
  TRIM LAYER "-> &GAS -> TRIM -> layer" ...
       ION "-> &GAS -> TRIM -> ion" ...
       WORK-FUNCTION "-> &GAS -> TRIM -> work" ...
       FANO-FACTOR "-> &GAS -> TRIM -> fano" ...
       RANGE-FILE "-> &GAS -> TRIM -> range" ...
       EXYZ-FILE "-> &GAS -> TRIM -> exyz"
!W
3 layer The layer within the TRIM calculation which corresponds to the gas volume in Garfield. 3 ion The ion of interest in the TRIM calculation. 3 work The work function, in eV. 3 fano The fano factor. 3 range The filename of the TRIM output file, called RANGE_3D.txt by default. 3 exyz The filename of the TRIM output file, called EXYZ.txt by default. 2 WRITE Writes a compact format gas dataset to be read by the "-> &GAS -> GET" instruction. The use of this instruction is strongly recommended when you compute the electron transport properties with "-> &GAS -> MAGBOLTZ" or with "-> &GAS -> 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 "-> &GAS -> TABLE" statement. The dataset contains initialisation information for "-> &GAS -> Heed", which will automatically be performed when re-reading the file with GET. Similarly, "-> &GAS -> SRIM" energy loss, range and straggling tables are included in the compact format gas datasets. 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 be sent to the author of Garfield for recovery. Files written with WRITE should in principle not be edited. These files are also not intended to serve as easily legible tables. Use the "-> &GAS -> OPTIONS -> GAS-PRINT" option or procedures like "-> Call -> DRIFT_VELOCITY" to obtain legible tables. Writing takes place while the section is being left, not when the WRITE command is issued. Use e.g. "-> &MAIN" to close the section. The statement can appear at any place in the gas section. Format: !W
  WRITE   [DATASET] "-> &GAS -> WRITE -> file" ["-> &GAS -> WRITE -> member"]   [[REMARK] "-> &GAS -> WRITE -> remark"]
!W
Example: !W
  "-> Global" gas_file `Ar_70_iso_30.gas`
  "-> Global" gas_member `exb`
  "-> Global" p 760
  "-> &GAS"
  Call "-> Call -> inquire_member"(gas_file,gas_member,`gas`,exist)
  If exist Then
     "-> &GAS -> get" {gas_file,gas_member}
  Else
     write {gas_file,gas_member}
     "-> &GAS -> pressure" {p} Torr
     "-> &GAS -> magboltz" argon 70 isobutane 30 ...
           angle-range 0 10 n-angle 6 ...
           b-range 0.4 1.2 n-b 5 ...
           e-range 100 300000 n-e 25 ...
           coll 25
  Endif
!W
Since Magboltz consumes a large amount of CPU time, we use the WRITE command to store the gas tables. When the same input file is run next time, the "-> Call -> INQUIRE_MEMBER" procedure will detect that the gas tables already exist and a "-> &GAS -> GET" is issued instead of a "-> &GAS -> MAGBOLTZ" command. 3 file The name of the "-> dataset -> structure -> file" in which you wish to write the gas description. You may prefix the dataset name with the keyword DATASET, but this is mandatory only if you wish to place a "-> &GAS -> WRITE -> remark" before the dataset name. If you use the DATASET keyword, then you must also use the REMARK keyword if you wish to add a remark to the member. If you do not use the DATASET keyword, then the first argument is interpreted as file name, the 2nd as member name and the 3rd and following arguments as remark. [The file name is mandatory, no default is provided.] 3 member The name by which you will want to reference the "-> dataset -> structure -> member" when retrieving it. The member name should follow the file name. [The member name is by default set to "< none >".] 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. You may prefix the remark with the keyword REMARK, provided you also prefix the dataset name with DATASET. If you do not use these keywords, then the 3rd and following arguments are interpreted as remark. [The field is left blank by default.] 1 &OPTIMISE This section contains a heterogeneous set of commands which assist in finding optimal potential settings, which compute the forces acting on the wire, which add space charge and which modify the chamber layout. Format: !W
  &OPTIMISE
!W
2 overview The optimisation section contains the instructions which fall in the following categories: !Wul_start - optimisation of potentials and calculation of forces - modification of the cell structure - three dimensional charges - general purpose instructions !Wul_end Optimisation of potential settings !Wtable_start !T+IP + . -------------------------------------------------------------------------- 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 -------------------------------------------------------------------------- !Wtable_end Modification of the cell structure: !Wtable_start !T+IP + . -------------------------------------------------------------------------- Command Short description -------------------------------------------------------------------------- ADD Adds elements to the cell CHANGE-VOLTAGES Modifies the wire, plane and tube potentials DELETE Deletes elements from the cell -------------------------------------------------------------------------- !Wtable_end Three dimensional charges: !Wtable_start !T+IP + . -------------------------------------------------------------------------- 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 -------------------------------------------------------------------------- !Wtable_end Adding a background field: !Wtable_start !T+IP + . -------------------------------------------------------------------------- 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 SAVE-FIELD-MAP Saves a background field map in binary format -------------------------------------------------------------------------- !Wtable_end Editing and inspecting the gas tables: !Wtable_start !T+IP + . -------------------------------------------------------------------------- Command Short description -------------------------------------------------------------------------- LIST-EXCITATIONS List excitation and ionisation levels PENNING-TRANSFERS Enables and disables Penning transfers PLOT-GAS Makes the gas plots PRINT-GAS Prints the gas tables -------------------------------------------------------------------------- !Wtable_end General purpose instructions: !Wtable_start !T+IP + . -------------------------------------------------------------------------- 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 -------------------------------------------------------------------------- !Wtable_end 2 ADD This instruction adds one or more elements to the cell. The coordinate system can not be changed by this instruction. This can only be done in the cell section. The symbolic variables from the cell section as entered with the "-> &CELL -> DEFINE" command 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 "-> &OPTIMISE -> CHANGE-VOLTAGES" instead. An ADD statement causes the loss of the current electrode selection established with a "-> &OPTIMISE -> SELECT" statement. Format: !W
  ADD [PERIODICITY {X|Y|PHI} "-> &OPTIMISE -> ADD -> length"] ...
      [PLANE {X|Y|R|PHI} "-> &OPTIMISE -> ADD -> coordinate" ...
             [VOLTAGE "-> &OPTIMISE -> ADD -> voltage"]] ...
             [LABEL "-> &OPTIMISE -> ADD -> label"]
      [WIRE LABEL "-> &OPTIMISE -> ADD -> label" ...
            AT "-> &OPTIMISE -> ADD -> position" ...
            [VOLTAGE "-> &OPTIMISE -> ADD -> voltage"] ...
            [DIAMETER "-> &OPTIMISE -> ADD -> diameter"]] ...
            [TENSION "-> &OPTIMISE -> ADD -> tension"]] ...
            [LENGTH "-> &OPTIMISE -> ADD -> length"]] ...
            [DENSITY "-> &OPTIMISE -> ADD -> density"]]
!W
3 length The length of the periodicity, in cm for x and y, in degrees for \φ. Periodicities in \φ must divide 360\°, they are rounded if that is not the case. Periodicities in r are not permitted. 3 coordinate The position of the plane, in cm for x, y and r, in degrees for \φ. The r coordinate of a circular plane must be\ >\ 0. [This is a mandatory parameter; no default is provided.] 3 voltage The potential of the wire or the plane in Volt [Default: 0\ V]. 3 label A single character by which you can identify the wire or the plane in "-> &FIELD -> SELECT" statements. The label 'S' has a special meaning in that electrodes with this label are by default selected. [Planes are by default not given a "-> &CELL -> PLANE -> label", a "-> &CELL -> ROWS -> label" is mandatory for wires.] 3 position The location of the new wire. This is a set of two numbers (x,y) or (r,\φ) depending on "-> &CELL -> methods -> coordinate_system" used when the cell was entered. The units of x, y and r is cm, \φ is in degrees. [No default, these are mandatory parameters.] 3 diameter The diameter of the new wire, expressed in cm. [Default: 0.01\ cm.] 3 tension The weight used to stretch the new wire, expressed in grams. Used by the "-> &OPTIMISE -> FORCES" command to estimate the wire displacement under gravitational and electrostatic forces. [Default: 50\ grams.] 3 length The length of the new wire, expressed in cm. Used by the "-> &OPTIMISE -> FORCES" command to estimate the wire displacement under gravitational and electrostatic forces. [Default: 100\ cm.] 3 density The density of the material of which the new wire is made, expressed in g/cm\³. Used by the "-> &OPTIMISE -> 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\³, i.e. 20\ \μm gold-plated tungsten wire.] 2 AREA Changes the plane over which the optimisation is carried out. Only relevant if optimisation by "-> &OPTIMISE -> SET -> 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 "-> &OPTIMISE -> DRIFT-AREA" command. Format: See the "-> &FIELD -> AREA" command in the field section. 2 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 "-> &FIELD -> 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 "-> &OPTIMISE -> 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. Since the background field map and the main field map occupy the same storage area, you can not apply a field map derived background field to a main field that is also supplied as a field map. Format: !W
  BACKGROUND-FIELD ...
       VOLTAGE "-> &OPTIMISE -> BACKGROUND-FIELD -> formula"  EX formula  EY formula  [EZ formula]
!W
Example: !W
  background-field voltage=   "-> algebra -> functions -> cos"(2*x)*"-> algebra -> functions -> sin"(2*y) ...
                   ex=      2*sin(2*x)*sin(2*y) ...
                   ey=     -2*cos(2*x)*cos(2*y)
!W
3 formula The background field should be entered as formulae in terms of the following variables: !Wtable_start !T+P + . --------------------------------------------------------------- Variable Meaning --------------------------------------------------------------- X (or R) x- or r-coordinate Y (or PHI) y- or \φ-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 --------------------------------------------------------------- !Wtable_end 2 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 if the matrix is still in memory, and is therefore considerably faster than "-> &OPTIMISE -> ADD" for large cells. You must 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: !W
  CHANGE-VOLTAGES {WIRE "-> &OPTIMISE -> CHANGE-VOLTAGES -> wire" | PLANE "-> &OPTIMISE -> CHANGE-VOLTAGES -> plane" | TUBE} VOLTAGE "-> &OPTIMISE -> CHANGE-VOLTAGES -> voltage" ...
!W
Example: !W
  ch-v     w 1 v 1000      w 2 v 3000
!W
Changes the voltage on wire\ 1 to 1000\ V and on wire\ 2 to 3000\ V. 3 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 -> OPTIONS -> CELL-PRINT" in the cell section or issue "-> &OPTIMISE -> PRINT-CELL" in the optimisation section) or by the wire "-> &CELL -> ROWS -> label" that you used when entering the wires with the "-> &CELL -> ROWS" statement. [No default, this is a mandatory parameter.] 3 plane The planes of which the voltage is to be changed can either be selected by name (LEFT, RIGHT, UP, DOWN) or by the "-> &CELL -> PLANE -> label" that you can have entered with the "-> &CELL -> PLANE" statement. [No default, this is a mandatory parameter.] 3 voltage The new voltage to be assigned to the wire, plane or tube. [To be specified in Volt.] 2 CHARGES !W
The current version of Garfield only takes point charges into account in a small number of configurations. !W
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: !W
  CHARGES
  x y z q
  x y z q
  ...
  (blank line)
!W
Example: !W
  charges
  0 0 0 100
  1 1 1 200
!W
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. 3 position The position should be given as 3-dimensional coordinates (x,y,z) and in cm. 3 charge As for wires, Garfield does not use scaling factors in its potential functions for point charges. The potential function used for an isolated three-dimensional point charge is: !W
  V = q/r
!W
where r is the distance between the charge and the point where the potential is to be calculated. It follows that the charge q should be expressed in units of V.cm. To convert from C to this unit, one should divide by 4\π\ε\0\. 2 DELETE Not yet available, see "-> &OPTIMISE -> ADD". 2 DELETE-BACKGROUND-FIELD Removes the background field. Format: !W
  DELETE-BACKGROUND-FIELD
!W
Example: !W
  del-backgr
!W
2 DELETE-CHARGES Removes all three dimensional charges. Format: !W
  DELETE-CHARGES
!W
Example: !W
  DELETE-CHARGES
!W
2 DELETE-FIELD-MAP Deletes the field map. Format: !W
  DELETE-FIELD-MAP
!W
Example: !W
  DELETE-FIELD-MAP
!W
2 DISPLAY Prints the current potential settings. Format: !W
  DISPLAY
!W
2 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 "-> &OPTIMISE -> AREA". Format: See the "-> &FIELD -> AREA" command in the field section. 2 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 "-> &FIELD -> SELECT", are summed if the GROUP option is selected. Format: !W
  FACTOR [GRID | WIRE | TRACK] ...
         [NOGROUP | GROUP]
!W
Example: !W
  factor
!W
(All defaults, GRID and NOGROUP, are accepted.) 2 FIELD-MAP The FIELD-MAP command of the optimisation section is used to study configurations where the basic field can be computed analytically from wires and planes, but where there is either an additional field component or a weighting field which is not known in analytic form: !Wul_start - Since analytic solutions exist for only a few 3-dimensional configurations, one often uses finite element methods to compute the field distortions caused by space charge. When computing a background field due to additional charges, all conductors in the chamber should be set to 0\ V. This ensures that the boundary conditions are respected when the basic field and the background field are superimposed. Background fields usually need scaling since one wishes to study the perturbations as function of the amount of charge. This scaling is performed by the "-> &OPTIMISE -> BACKGROUND-FIELD" command. The field in the chamber is not modified until this command has been executed. - In e.g. cathode pad chambers, the drift field is known analytically, but the weighting field for the pads is more easily computed with the help of finite element methods. When computing signals, you identify each of the weighting fields that you have entered by their "-> &CELL -> FIELD-MAP -> FILES -> label" to the "-> &SIGNAL -> SELECT" command. Weighting fields have a fixed normalisation and the BACKGROUND-FIELD command should therefore not be used for weighting fields. !Wul_end Also the cell section has a "-> &CELL -> 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 the same storage and can therefore not be used at the same time. Format: See the "-> &CELL -> FIELD-MAP" command in the cell section. Example: See the attached "-> &OPTIMISE -> FIELD-MAP -> weighting_field" example. 3 weighting_field In the following example, we compare the weighting field for a strip in a cathode strip chamber as computed using ANSYS and the weighting field for the same strip neglecting the presence of the wire, using a z-"-> &CELL -> PLANE -> strip" on a cathode plane. The following command file illustrated how one can produce the finite-element weighting field: (refer to the "-> &CELL -> FIELD-MAP -> FILES -> format -> ANSYS-solid-123" recipe for explanations) !W
  FINISH  
  /CLEAR,START
  /PREP7  
  ! No polynomial elements
  /PMETH,OFF,1

  ! Set electric preferences
  KEYW,PR_ELMAG,1
  KEYW,MAGELC,1   

  ! Select element
  ET,1,SOLID123

  ! Material properties
  MP,PERX,1,1e10  ! Metal
  MP,RSVX,1,0.0   !
  MP,PERX,2,1.0   ! Gas
  MP,PERX,3,4.0   ! Permittivity of the FR4

  ! Construct the strips in mm
  w = 4          ! Strip width
  l = 10         ! Length modeled along the wire
  pitch = 2      ! Wire pitch
  h = 0.10       ! Strip thickness
  open = 0.500   ! Gap between strips
  gap = 2.5      ! Gap between strip and wire
  d = 0.050      ! Wire diameter
  sub = 2        ! Substrate thickness
  BLOCK, -pitch/2, pitch/2, 0, h, -w/2, w/2             ! 1: Strip to be read out
  BLOCK, -pitch/2, pitch/2, 0, h, -l/2, -w/2-open       ! 2: Skirt 1
  BLOCK, -pitch/2, pitch/2, 0, h, w/2+open, l/2         ! 3: Skirt 2
  BLOCK, -pitch/2, pitch/2, -sub, 0, -l/2, l/2          ! 4: Substrate
  WPOFFS,,,-l/2
  CYL4,  0,  gap, d/2, ,   , ,l                         ! 5: Anode wire
  WPOFFS,,,l/2
  BLOCK, -pitch/2, pitch/2, -sub, 2*gap, -l/2, l/2      ! 6: Gas

  ! Subtract the strips and wires from the gas
  VSEL, ALL
  VSBV,6,ALL,,,KEEP         ! gas becomes 7

  ! Glue everything together, 1 = strip, 2 = skirt, 3 = skirt, 5 = wire, 6 = substrate, 7 = gas
  VSEL,ALL
  VGLUE, ALL

  ! Colour the parts
  /COLOR, VOLU, YELLOW, 1 ! Read-out strip
  /COLOR, VOLU, GREEN, 2  ! Skirt
  /COLOR, VOLU, GREEN, 3  ! Skirt
  /COLOR, VOLU, RED, 6    ! Substrate

  ! Assign material attributes
  VSEL, S, VOLU, , 6      ! FR4
  VATT, 3
  VSEL, S, VOLU, , 1      ! strip
  VSEL, A, VOLU, , 2      ! skirt
  VSEL, A, VOLU, , 3      ! skirt
  VSEL, A, VOLU, , 5      ! wire
  VATT, 1
  VSEL, S, VOLU, , 7      ! gas
  VATT, 2

  ! Voltage boundaries for a weighting field
  VSEL,S,,,1
  ASLV, S
  DA, ALL, VOLT, 1                 ! Readout strip
  VSEL,S,,,2
  VSEL,A,,,3
  VSEL,A,,,5
  ASLV, S
  DA, ALL, VOLT, 0                 ! All other metal
  VSEL,S,,,7
  ASLV, S
  ASEL, R, LOC, Y, 2*gap
  DA, ALL, VOLT, 0                 ! Cathode plane without strips
  VSEL,S,,,7
  ASLV, S
  ASEL, R, LOC, X, -pitch/2
  DA, ALL, SYMM                    ! Continuity
  VSEL,S,,,7
  ASLV, S
  ASEL, R, LOC, X, +pitch/2
  DA, ALL, SYMM                    ! Continuity
  VSEL,S,,,7
  ASLV, S
  ASEL, R, LOC, Z, -l/2
  DA, ALL, SYMM                    ! Continuity
  VSEL,S,,,7
  ASLV, S
  ASEL, R, LOC, Z, +l/2
  DA, ALL, SYMM                    ! Continuity
  VSEL,S,,,6
  ASLV, S
  ASEL, R, LOC, Y, -sub
  DA, ALL, VOLT, 0                 ! Backplane

  ! Meshing
  VSEL, ALL
  ASLV, S

  MSHKEY,0
  SMRT, 6
  VMESH, ALL

  ! Solve the field
  /SOLU
  SOLVE   
  FINISH  

  ! Display the solution
  /POST1  
  /EFACET,1   
  PLNSOL, VOLT,, 0

  ! Write the solution to files
  /OUTPUT, PRNSOL, lis
  PRNSOL
  /OUTPUT

  /OUTPUT, NLIST, lis
  NLIST,,,,COORD
  /OUTPUT

  /OUTPUT, ELIST, lis
  ELIST
  /OUTPUT

  /OUTPUT, MPLIST, lis
  MPLIST
  /OUTPUT
!W
The resultant field map of the weighting potential is called PRNSOL.lis and it is accompanied by an ELIST.lis file that contains the mesh structure, an NLIST.lis file with node coordinates and an MPLIST.lis file with material properties. These 3 files must be kept together in a directory from where they are read with the following Garfield commands: !W
  "-> &CELL"
  "-> &CELL -> plane" y=0 v=0 z-strip -0.2 0.2 "-> &CELL -> PLANE -> gap" 0.5 label b // Create a strip called "B"
  plane y=0.5 v=0
  "-> &CELL -> rows"
  s 1 0.0050 0 0.25 1200

  "-> &CELL -> periodicity" x=0.25

  "-> &OPTIMISE"
  Global bin `csc.bin`
  If exist(bin) Then                // Read binary if it exists
     "-> &OPTIMISE -> read-field-map" {bin}
  Else
     "-> &OPTIMISE -> field-map" files weighting-field "PRNSOL.lis" label A ... // Call this weighting field "A"
               units=mm ...
               ansys-solid-123 ...
               x-periodic z-periodic
     "-> &OPTIMISE -> save-field-map" {bin}           // Otherwise, create a binary
  Endif

  "-> &GAS"
  "-> &GAS -> get" "Ar_80_CO2_20.gas" // Assumes the transport file exists
  "-> &GAS -> add" ion-mobility 1.5e-6

  "-> &SIGNAL"
  "-> &SIGNAL -> select" a b // Select both weighting fields
  "-> &SIGNAL -> area" -0.25 0 -0.5  0.25 0.5 0.5
  "-> &SIGNAL -> window" 0 0.025

  "-> &SIGNAL -> reset" "-> &SIGNAL -> reset -> signals"
  Call "-> Call -> drift_ion"(0.0025, 0.26)
  Call "-> Call -> add_signals"
  Call "-> Call -> get_signal"(1,time1,dir1,cross1) // Retrieve the finite element signal ("A")
  Call "-> Call -> get_signal"(2,time2,dir2,cross2) // Retrieve the no-wire signal ("B")

  Call "-> Call -> plot_frame"("-> algebra -> functions -> minimum"(time1 & time2), "-> algebra -> functions -> minimum"(dir1+cross1 & dir2+cross2), ...
     "-> algebra -> functions -> maximum"(time1 & time2), "-> algebra -> functions -> maximum"(dir1+cross1 & dir2+cross2), ...
     `Time [microsec]`, `Current`, `Comparing weighting fields`)
  Call "-> Call -> plot_line"(minimum(time1 & time2), 0, maximum(time1 & time2), 0, `comment`)
  Call "-> Call -> plot_line"(time1, dir1+cross1, `function-1`)
  Call "-> Call -> plot_line"(time2, dir2+cross2, `function-2`)
  Call "-> Call -> plot_end"

  "-> &SIGNAL -> area" view x=0
  "-> &SIGNAL -> plot-field" "-> &SIGNAL -> plot-field -> vector"
!W
In the above example, an ion is drifted from the vicinity of the anode wire towards the cathode plane that is not read out. The signal induced by this moving charge is computed twice: !Wul_start - in orange: using the finite element field map which takes the presence of the anode wire into account; - in green: using the weighting field for the strip neglecting the anode wire. !Wul_end The comparison of these currents shows a clear difference: while the current computed with the finite element map is bipolar, as it should for a charge moving between electrodes that are not read out, the current computed neglecting the wire (in green) is unipolar: !W The reason for this difference readily becomes apparent when comparing the weighting field maps (left: finite elements, including the wire, right: neglecting the wire): !W !W 3 space_charge In this example, we show how to add, with the help of the finite element method, space charge or surface charge to a chamber. Space charge can, in a number of cases, also be added by analytic means using the "-> &OPTIMISE -> CHARGES" command but this method is not discussed here. This example uses ANSYS, which is unit-free for what concerns distances. This affords flexibility as long as only symmetry and voltage boundary conditions are used - voltage and length units are decoupled. Charges in contrast are coupled to voltages both via \ε\0\ and via an implicit length, as can be seen from the expression for a potential generated by a point charge: !W
         q
  V = --------
      4 \π \ε\0\ r

  \ε\0\ ~ 8.854\×10\-14\ C/(V.cm)
!W
This leads to two scaling factors: !Wol_start 1. ANSYS apparently assumes \ε\0\ to be expressed in units of C/(V.m). To be compatible with the Garfield unit of C/(V.cm), the charges need to be multiplied by 100. 2. Assume that the model is constructed using length-units of f\ \×\ cm (f equals 0.1 for mm, 1 for cm and 100 for m). When reading the field maps and using the "-> &CELL -> FIELD-MAP -> unit" information supplied in the "-> &CELL -> FIELD-MAP" command, Garfield scales all distances to cm, the length unit used by Garfield. This is sufficient for voltage and symmetry boundary conditions, but not for potentials that arise from charges. For these, inside ANSYS, unscaled distances (r in the above formula) are used. To compensate for this, a further factor of 1/f must be applied to the charges that are entered in ANSYS. !Wol_end Combining these factors, the charges are entered as-is when native units of metre are used in ANSYS. Otherwise, the charges need to be scaled by a factor 100/f, i.e. a factor of 100 if cm is used and a factor 1000 for models in mm. In ANSYS, charges can be entered as volume charge densities or as surface charge densities (amongst other possibilities). In case only the total charge is known, then this charge has to be divided by the volume or the surface area of the charge carrier. Example for a volume charge: !W
  ! Parameters of the device
  unit = 1000            ! Units: 1000 for mm, 100 for cm, 1 for m
  r  = 0.1               ! Radius [mm]
  pi = 3.14159265        ! pi
  qe = 1.60217646e-19    ! Electron charge [C]
  charge = 12345*unit*qe ! Total charge in the device

  ! Create a ball which will act as charge carrier
  SPH4,0,0,r 

  ! Distribute charge in the volume of the ball
  VSEL, S, VOLU, ,1
  BFV,ALL,CHRG,charge/(4.0*pi*r*r*r/3.0)
!W
When surface charges are used, an additional precaution needs to be taken in that the surface area for e.g. a sphere has to be multiplied by an ununderstood factor of 2: !W
  ! Distribute charges over the surfaces of the ball
  VSEL, S, VOLU, ,1
  ASLV, S
  SFA,ALL,,CHRGS,charge/(2*4.0*pi*r*r)
!W
It is therefore strongly recommended to verify the integral charge as follows: !W
  Global r = 0.1             // sufficiently large to wrap around all charges
  Global eps0 = 8.854e-14    // C/(V.cm)
  Global qe = 1.60217646e-19 // C
  Call "-> Call -> integrate_charge"(0, 0, 0, r, qi)
  Say "Electron charges: {qi*4*pi*eps0/qe}"
!W
2 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 "-> &CELL -> 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 "-> &CELL -> GRAVITY". The wires on which this instruction operates are those selected by the "-> &FIELD -> SELECT" instruction. These wires do not necessarily have to be located within the current "-> &OPTIMISE -> AREA". When one uses the "-> &OPTIMISE -> FORCES -> ITERATE" option to study collective wire motion, then it is crucial to select all wires that are likely to move. This instruction offer 2 levels of accuracy, called "-> &OPTIMISE -> FORCES -> DETAILED" and "-> &OPTIMISE -> FORCES -> FAST". All wires are restored to their nominal location once the calculations have been completed. To study the effect that sag has on the gain, one should displace the wires in the cell section. Format: !W
  FORCES ["-> &OPTIMISE -> FORCES -> PRINT-SAG" | NOPRINT-SAG] ...
         ["-> &OPTIMISE -> FORCES -> PLOT-SAG" | NOPLOT-SAG] ...
         [NOKEEP-SAG | "-> &OPTIMISE -> FORCES -> KEEP-SAG"] ...

         ["-> &OPTIMISE -> FORCES -> PRINT-FORCES" | NOPRINT-FORCES] ...
         ["-> &OPTIMISE -> FORCES -> PLOT-FORCES" | NOPLOT-FORCES] ...
         [NOKEEP-FORCES | "-> &OPTIMISE -> FORCES -> KEEP-FORCES"] ...

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

         ["-> &OPTIMISE -> FORCES -> ITERATE" [n_iter] | NOITERATE] ...
         ["-> &OPTIMISE -> FORCES -> TOLERANCE" tolerance] ...
         ["-> &OPTIMISE -> FORCES -> UPDATE-SCALING-FACTOR" factor] ...
         ["-> &OPTIMISE -> FORCES -> OFFSET" wire x_offset y_offset] ...
         
         ["-> &OPTIMISE -> FORCES -> ELECTROSTATICS" | NOELECTROSTATICS] ...
         ["-> &OPTIMISE -> FORCES -> GRAVITY" | NOGRAVITY]
!W
Example: !W
  select s
  forces detailed keep-sag
!W
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). 3 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. 3 DETAILED Requests a calculation of the wire sag profiles, without any a priori assumption regarding the shape of the wire. In this mode, the program uses in its computations the force that acts on the wire if it is (artificially) offset. These forces are computed by solving the capacitance equations for every (set of) wire locations for which one needs a force. Since the force usually displays smooth variations with offset, the program computes the forces only for a number of locations ("-> &OPTIMISE -> FORCES -> SCANNING-GRID") in the vicinity ("-> &OPTIMISE -> FORCES -> SCANNING-AREA") of the nominal location and interpolates in this table ("-> &OPTIMISE -> FORCES -> INTERPOLATION-ORDER") when a force is needed. 3 SCANNING-GRID When the "-> &OPTIMISE -> FORCES -> 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 explicitly (i.e. by solving the capacitance matrix), an interpolation is performed on a grid (the interpolation order can be chosen with "-> &OPTIMISE -> FORCES -> 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 "-> &OPTIMISE -> FORCES -> SCANNING-AREA".) The number of grid lines can be controlled 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.] 3 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 explicitly 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. 3 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. 3 nstep See "-> &OPTIMISE -> FORCES -> nshot". 3 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. 3 EXTRAPOLATE By default, the calculation stops if a point of the wire is found at a position not covered by the "-> &OPTIMISE -> FORCES -> 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). 3 ITERATE Requests iterating over the positions of all "-> &OPTIMISE -> SELECT"ed 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 !Wol_start 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. !Wol_end The iteration is stopped when !Wul_start - the iteration converges because no wire moves by more than a "-> &OPTIMISE -> FORCES -> TOLERANCE"; - when the maximum permitted number of iterations has been reached. !Wul_end ITERATE can be used both with the "-> &OPTIMISE -> FORCES -> FAST" and with the "-> &OPTIMISE -> FORCES -> 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 "-> &OPTIMISE -> FORCES -> 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 "-> &OPTIMISE -> FORCES -> UPDATE-SCALING-FACTOR". 3 TOLERANCE This parameter enters as convergence criterion for iterations over all wires ("-> &OPTIMISE -> FORCES -> 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\ \μm.] 3 UPDATE-SCALING-FACTOR (not yet used) 3 OFFSET When performing iterations over all wires ("-> &OPTIMISE -> FORCES -> 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).] 3 GRAVITY The gravitational force on the wire is included in the sag computation. This option is meaningful only if the "-> &CELL -> GRAVITY" command has been used to set a direction in which gravity acts on the wires. [This is default.] 3 ELECTROSTATICS The electrostatic force on the wire is taken into account when calculating the wire sag. [This is default.] 3 PRINT-SAG Prints depending on the requested level of detail in the calculation, the following is printed: !Wul_start - "-> &OPTIMISE -> FORCES -> FAST": the expected maximum sag or - "-> &OPTIMISE -> FORCES -> DETAILED": the above + the sag profile. !Wul_end [This is default.] 3 PLOT-SAG Plots the sag profiles if the "-> &OPTIMISE -> FORCES -> DETAILED" option has been selected. The x-component of the sag is plotted with the representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" while the y-component is shown with the representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". [This is default.] 3 KEEP-SAG When this option is selected, the wire sag is stored in global variables: !Wul_start - FAST: the maximum sag from the parabolic approximation is stored as two globals of type "-> algebra -> variables -> types -> Number", called SHIFT_X_n and SHIFT_Y_n, where n is the wire number. - DETAILED: the sag profile is stored in a set of 3 globals of type "-> algebra -> variables -> types -> Matrix" called Z_n, SAG_X_n and SAG_Y_n, where n is the wire number. !Wul_end The wire elongation is stored in STRETCH_n, a "-> algebra -> variables -> types -> Number", in both cases. In case these global variables are already in use, then their original contents will be lost. These arrays can be used to obtain the sag at any point on the wire by such statements as: !W
  "-> 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})."
!W
You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. The global variable "-> algebra -> variables -> predefined -> 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.] 3 PRINT-FORCES Prints, if the "-> &OPTIMISE -> FORCES -> 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.] 3 PLOT-FORCES Plots, if the "-> &OPTIMISE -> FORCES -> 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 "-> &OPTIMISE -> FORCES -> KEEP-FORCES" option and plot the forces with the "-> Call -> PLOT_SURFACE" or "-> Call -> PLOT_CONTOURS" procedure. The x-component of the force is plotted with the representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" while the y-component is shown with the representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". [This option is off by default.] 3 KEEP-FORCES When this option is selected, the table of electrostatic forces acting on the wires is stored as: !Wul_start - "-> &OPTIMISE -> FORCES -> FAST": Two globals of type "-> algebra -> variables -> types -> Number" called FORCE_X_n and FORCE_Y_n where n is the wire number. - "-> &OPTIMISE -> FORCES -> DETAILED": two globals of type "-> algebra -> variables -> types -> Matrix" called FX_n and FY_n where n is the wire number contain the forces on a grid within the "-> &OPTIMISE -> FORCES -> SCANNING-AREA". Two further vectors, X_F_n and Y_F_n contain the abscissa for these two matrices. !Wul_end 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 original contents will be lost. This option can for instance be used to make a 3-dimensional graph of the electrostatic forces acting on the wire as function of the wire shift: !W
!W !W

!WThe plot shows the forces in a chamber with a planar and a wire cathode, !Was for instance used for the read-out of a TPC. The plot was made with !Wthe following set of commands: !W

!D1
  Example:
  "-> &CELL"
  "-> &CELL -> plane" y -0.2
  pl y  4
  "-> &CELL -> rows"
  s * * 0 0 2000
  p * * 0 0.2 0
  p * * 0.2 0.2 0

  "-> &CELL -> periodicity" x 0.4

  "-> &OPTIMISE"
  "-> &OPTIMISE -> forces" detailed keep-forces noplot-sag ...
         noplot-forces noprint-sag ...
         scanning-grid 25 25 ...
         scan-area -0.15 -0.15 +0.15 +0.15
  Call "-> Call -> plot_surface"(fy_1,30,120,x_f_1,y_f_1, ...
     `x`,`y`,`y-Component of F`)
!W
!W
One can also use this option to obtain the electrostatic forces acting on the wire in their final position: !W
  * 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 "-> Call -> dimensions"(x_f_1,ndim,dim)
  Global nx="-> algebra -> functions -> number"(dim)
  Call dimensions(y_f_1,ndim,dim)
  Global ny="-> algebra -> functions -> number"(dim)
  Call "-> Call -> book_matrix"(point,2,1)
  Global point[1;1]=xc
  Global point[2;1]=yc
  Call "-> Call -> interpolate"(fx_1,x_f_1,y_f_1,point,out)
  Global fxc="-> algebra -> functions -> number"(out)
  Call interpolate(fy_1,x_f_1,y_f_1,point,out)
  Global fyc="-> algebra -> functions -> number"(out)
  Call "-> Call -> delete_matrix"(dim,point,out)
  Say "Electrostatic forces in central position: ({fxc,fyc}) N/cm."
!W
You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. The variable "-> algebra -> variables -> predefined -> 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.] 2 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 "-> &OPTIMISE -> SET" instruction. The grid is common to all sections. Format: !W
  GRID  "-> &OPTIMISE -> GRID -> number"_of_steps_in_x  [number_of_steps_in_y]
!W
Example: !W
  GRID 5
!W
3 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 \φ) spacing. [Default is 25 for both.] 2 LIST-CHARGES Produces a list of the currently present three dimensional charges. Format: !W
  LIST-CHARGES
!W
Example: !W
  LIST-CHARGES
!W
2 LIST-EXCITATIONS Prints a list of all excited states with their threshold energy, the ionisation levels to which they can (and can not) transfer their energy, as well as the transfer rates. The same list is shown when issues a "-> &OPTIMISE -> PENNING-TRANSFERS" command without arguments. 2 OPTIONS No local options in this section, but the command can be used to set top level "-> OPTIONS". 2 PENNING-TRANSFERS Sets the Penning transfer rates. The Magboltz program contains, as part of its cross section catalogue, excitation and dissociative-excitation cross sections. Using these, the program computes for each electric field, and if applicable, also each magnetic field and (E,B) angle, the rates at which excited molecules are produced. Some of these excited molecules can transfer their excess energy to other molecules, which become ionised as a result. This energy transfer is known as Penning effect. It leads to a, sometimes massive, increase of the gain. The excited and ionised states are listed if no arguments are given, see "-> &OPTIMISE -> LIST-EXCITATIONS". This command requires the presence of excitation and ionisation rates in the gas tables. These can currently only be entered by running Magboltz version\ 7, called from Garfield version\ 7.22 or later. Format: !W
  PENNING-TRANSFERS "-> &OPTIMISE -> PENNING-TRANSFERS -> state"1 "-> &OPTIMISE -> PENNING-TRANSFERS -> rate"1 ["-> &OPTIMISE -> PENNING-TRANSFERS -> PERMITTED" | "-> &OPTIMISE -> PENNING-TRANSFERS -> FORCED"] [DELAY "-> &OPTIMISE -> PENNING-TRANSFERS -> delay" ] [RANGE "-> &OPTIMISE -> PENNING-TRANSFERS -> range"]...
       state2 rate2 [PERMITTED | FORCED] ...
!W
Example: Let 50\ % of all excited neon states that have an energy above the ionisation energy of the admixture, cause ionisations !W
  penning Ne* 50
!W
3 state A string to select one or more excited states. This can be an explicit state. Their names are listed under the gas "-> &GAS -> MAGBOLTZ -> ingredient" descriptions. For instance, NEON-1S2 corresponds to the 1s\2\ excitation in the default description of neon, i.e. "-> &GAS -> MAGBOLTZ -> ingredient -> NEON-ANISOTROPIC". This may be a wildcard in which a * can represent any string. For instance, specifying Ne* will select all excited states of neon. The selection string may be entered in upper, lower or mixed case. Case is not significant. Not all Magboltz excited states are accessible at present in this form. Please contact the author in case your favoured state needs to be added. 3 rate The fraction of excited molecules that will ionise another molecule. This number has to be given in the form of a percentage, from 0 to 100. 3 delay Mean time needed for the transfer, in microsec. The actual time for each transfer is an exponentially distributed random number with the specified mean. 3 range Sigma of the distance, in each of the coordinate axes, between the excitation and the ionisation. The distance must be expressed in cm. The actual ionisation location is Gaussian distributed with specified sigma. 3 PERMITTED By default, only excited states that have a threshold energy above at least one of the ionisation levels will be considered. 3 FORCED Forces transfers also from excited states that have a threshold below the lowest ionisation level present in the gas mixture. Such transfers do not occur, as a rule. 2 PLOT-GAS Plots the transport properties of the gas. These plots are the same as those made in response to the "-> &GAS -> OPTIONS -> GAS-PLOT" option in the "-> &GAS" section. 2 PRINT-GAS Prints the transport properties of the gas. This table is the same as the one made in response to the "-> &GAS -> OPTIONS -> GAS-PRINT" option in the "-> &GAS" section. 2 POINTS When optimisation by "-> &OPTIMISE -> SET -> 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, "-> &OPTIMISE -> SET" uses the number set with POINTS. This number is used nowhere else. Format: !W
  POINTS  points_on_track
!W
Example: !W
  POINTS 50
!W
[Default: 20] 2 PRINT-CELL Produces a listing of the cell elements, like the one made at the end of the cell section if the "-> &CELL -> OPTIONS -> CELL-PRINT" option is in effect. Format: !W
  PRINT-CELL
!W
Example: !W
  PRINT-CELL
!W
2 READ-FIELD-MAP See the "-> &CELL -> FIELD-MAP" command in the cell section. 2 RESTORE Restores a previously "-> &OPTIMISE -> SAVE"d 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: !W
  RESTORE [reference_number]
!W
Example: !W
  "-> &OPTIMISE -> save"
  (program replies with the reference number 5; next you try:)
  "-> &OPTIMISE -> set" V to average on grid
  "-> &OPTIMISE -> display"
  (You notice you don't like the new settings and therefore\ ...)
  restore 5
!W
2 SAVE Saves the current set of potentials. The program replies with a number you should remember because it's required for retrieval with the "-> &OPTIMISE -> RESTORE" command: Format: !W
  SAVE
!W
2 SAVE-FIELD-MAP See the "-> &CELL -> SAVE-FIELD-MAP" command of the cell section. 2 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 "-> &OPTIMISE -> FORCES" instruction will try to compute displacements for the wires that have been selected and the "-> &OPTIMISE -> SET" instruction will vary the voltages on such wires. Selection of other electrodes than wires has no effect. Format: See the "-> &FIELD -> SELECT" command in the field section. Example: !W
  SEL (1 S) 2 F
!W
(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.) 2 SET SET is a key instruction in the optimisation section. It varies the potentials of the selected electrodes in an attempt to match as closely as possible a function of the potential and field in the chamber, called "-> &OPTIMISE -> SET -> field_function" to a function of the coordinates, called "-> &OPTIMISE -> SET -> target_function". Only the potentials on the electrodes that have been subject to a "-> &OPTIMISE -> SELECT" will be touched during the process. Electrodes that are put together in a group, are shifted collectively. The field and target functions are compared either over !Wul_start - "-> &OPTIMISE -> SET -> TRACK" option: the "-> &OPTIMISE -> TRACK"; - "-> &OPTIMISE -> SET -> GRID" option: a "-> &OPTIMISE -> GRID" covering the "-> &OPTIMISE -> AREA"; - "-> &OPTIMISE -> SET -> WIRES" option: the surfaces of the S wires. !Wul_end The command is used e.g. to adjust the voltages on the anode wires such that the field in their proximity has a given value. One can also use SET to adjust the potentials on a drift electrode in a TPC to get the proper drift field. Another application could be improving the drift isochrony from a track. 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: !Wul_start * The user defined maximum number of iterations is reached, * The relative change in Euclidean distance between the target and field function (on the sampling points) drops below an "-> &OPTIMISE -> SET -> \ε" threshold. * The maximum distance (of all sampling points) between the target and field function becomes smaller than a threshold "-> &OPTIMISE -> SET -> distance". * The functions cannot be brought closer together anymore by varying the potentials, * Variations of the potentials on two different electrodes cause identical effects. !Wul_end Format: !W
  SET "-> &OPTIMISE -> SET -> field_function" ...
      TO {AVERAGE | "-> &OPTIMISE -> SET -> target_function"} ...
      [WEIGHT "-> &OPTIMISE -> SET -> weight_function"] ...
      [ON {"-> &OPTIMISE -> SET -> TRACK" | "-> &OPTIMISE -> SET -> GRID" | "-> &OPTIMISE -> SET -> WIRES"}] ...
      [DISTANCE "-> &OPTIMISE -> SET -> distance"] ...
      [EPSILON "-> &OPTIMISE -> SET -> \ε"] ...
      [ITERATE-LIMIT "-> &OPTIMISE -> SET -> iterlim"] ... 
      ["-> &OPTIMISE -> SET -> PRINT" | NOPRINT]
!W
Examples: !W
  "-> &CELL"
  "-> &CELL -> plane" y=0 v=0 label=p
  plane y=2 v=-250 label=q
  "-> &CELL -> rows"
  s    1 0.0020  0        0.4 1400
  f    1 0.0125  0.2      0.4    0
  c    4 0.0067  0.1*i    0.8    0
  g    2 0.0067  0.2*i    1.4  -67

  "-> &CELL -> periodicity" x=0.4

  "-> &OPTIMISE"
  "-> &OPTIMISE -> track" -0.2 1.9 0.2 1.9
  "-> &OPTIMISE -> select" q
  set e on track to 125

  &FIELD
  "-> &FIELD -> track" 0.05 0 0.05 2
  "-> &FIELD -> plot-field" graph e range 100 150
!W
This is a TPC read-out cell similar to the one used by Aleph. It would not be practical to model the chamber with the membrane at its true location, i.e. several metres from the cell. It is therefore replaced by a plane at 2\ cm and we use to SET command to choose the voltage on this plane such that the drift field is 125\ V/cm. The graph verifies that the field has indeed reached the desired setting and that the plane is sufficiently far away from the cell to achieve a constant field. 3 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] 3 \ε 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 10\-4\) when your initial guess is quite good. Values smaller than 10\-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 10\-4\, the value is remembered from one SET command to the next.] 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. !Wtable_start !T+P + + . ---------------------------------------------------------------------- Variable Meaning Notes ---------------------------------------------------------------------- X or R x- or r-Coordinate - Y or PHI y- or \φ-Coordinate - EX or ER x- or r-component of E - EY or EPHI y- or \φ-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 ---------------------------------------------------------------------- !Wtable_end When using drift related quantities (AVALANCHE, DIFFUSION and TIME), one should take care to define a proper drift area via the "-> &OPTIMISE -> DRIFT-AREA" command. These quantities can not be used when optimising on the surface of one or more "-> &OPTIMISE -> SET -> WIRES". More variables can be added on demand. 3 GRID Specifies that the grid should be used to compare the target and field functions. The density of the grid is set with the "-> &OPTIMISE -> GRID" command, please ensure that the number of grid points is not excessive. Do not forget to set a proper "-> &OPTIMISE -> DRIFT-AREA" if you wish to optimise drift related quantities (AVALANCHE, DIFFUSION and TIME). 3 iterlim The maximum number of iterations you allow the program to make. [The default setting is 10.] 3 PRINT By default, some optimisation information is printed each cycle. This may be switched of by specifying NOPRINT. 3 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. !Wtable_start !T+P + + . ---------------------------------------------------------------------- Variable Meaning Notes ---------------------------------------------------------------------- X or R x- or r-Coordinate - Y or PHI y- or \φ-Coordinate - ---------------------------------------------------------------------- !Wtable_end 3 TRACK Specifies that the track should be used to compare the target and field functions. The number of track points can be set with "-> &OPTIMISE -> POINTS". Do not forget to set a proper "-> &OPTIMISE -> DRIFT-AREA" if you wish to optimise drift related quantities (AVALANCHE, DIFFUSION and TIME). 3 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: !Wtable_start !T+P + + . ---------------------------------------------------------------------- Variable Meaning Notes ---------------------------------------------------------------------- X or R x- or r-Coordinate - Y or PHI y- or \φ-Coordinate - ---------------------------------------------------------------------- !Wtable_end 3 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. 2 TRACK Sets the line which is used by the optimisation of the potentials as performed by the "-> &OPTIMISE -> SET -> TRACK" option of the "-> &OPTIMISE -> 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 "-> &DRIFT -> TRACK" command in the drift section. Example: !W
  TRACK 1 1 2 2
!W
1 &FIELD The field section is used to inspect the electrostatic aspects of your chamber. The main command of the section, "-> &FIELD -> PLOT-FIELD", enables plots contours, 3D views, vector fields and histograms of almost any field-related quantity. Format: !W
  &FIELD
!W
2 overview The instructions of the field section fall in 4 categories: !Wul_start - setting various parameters - plotting and printing - understanding the field - service instructions !Wul_end The use of this section is fairly straight-forward since it has only one frequently used instruction: "-> &FIELD -> PLOT-FIELD". Setting parameters: !Wtable_start !T+IP + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end Plotting and printing: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ PLOT-FIELD General purpose field plotting instruction PRINT General purpose field printing instruction ------------------------------------------------------------------------ !Wtable_end Understanding: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ CHECK Verifies charges and boundary conditions MULTIPOLE-MOMENTS Computes the multipole moments for a wire ------------------------------------------------------------------------ !Wtable_end Service instructions: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ SAMPLE Field value (see "-> Call -> ELECTRIC_FIELD") TIME Times the field calculations ------------------------------------------------------------------------ !Wtable_end Notes: !Wol_start 1. There are several instructions in the optimisation section that perform related tasks. 2. There are also procedure calls that perform related tasks: "-> Call -> ELECTRIC_FIELD", "-> Call -> ELECTRIC_FIELD_3", "-> Call -> MAGNETIC_FIELD", "-> Call -> MAGNETIC_FIELD_3", "-> Call -> INTEGRATE_CHARGE", "-> Call -> INTEGRATE_FLUX", "-> Call -> MAP_ELEMENT", "-> Call -> MAP_INDEX" and "-> Call -> MAP_MATERIAL". !Wol_end 2 AREA Sets the following things: !Wul_start - a "-> &FIELD -> AREA -> box" which limits the part of the chamber at which you wish to look, e.g. particles are not allowed to drift outside the box - a "-> &FIELD -> AREA -> plane", which is perpendicular to the direction under which you look at the chamber and which also serves as surface over which the field is sampled for contours, histograms etc. - a projection method to visualise the chamber, the "-> &FIELD -> AREA -> light" source, the reflective properties of the solids etc !Wul_end AREA commands are found in several sections: !Wul_start - field section: where the command establishes the plane on which e.g. contours are plotted - drift sections: where the command limits the region over which particles are allowed to drift and sets the viewing direction for plots of drift-lines - optimisation section: shares both the field and the drift area, respectively to set the optimisation plane and to limit drift-lines - signal section: shares the drift area !Wul_end The geometrical extent of the field and the drift area boxes are distinct, but the viewing plane is shared between the two. Format: !W
  AREA [xmin ymin xmax ymax | xmin ymin zmin xmax ymax zmax] ...
       [VIEW "-> &FIELD -> AREA -> plane"] ...
       [ROTATE "-> &FIELD -> AREA -> angle"] ...
       ["-> &FIELD -> AREA -> X-Y" | "-> &FIELD -> AREA -> R-PHI" | "-> &FIELD -> AREA -> X-Z" | "-> &FIELD -> AREA -> Y-Z" | "-> &FIELD -> AREA -> 3D" | "-> &FIELD -> AREA -> CUT" | "-> &FIELD -> AREA -> NEBEM"] ...
       ["-> &FIELD -> AREA -> LIGHT-ORIGIN" \φ_light \θ_light] ...
       ["-> &FIELD -> AREA -> REFLECTED-FRACTION" frac_refl] ...
       ["-> &FIELD -> AREA -> ABSORBED-FRACTION" frac_scat] ...
       ["-> &FIELD -> AREA -> COLOURS" ncol] ...
       [PARTIAL-BOX-TICKMARKS | "-> &FIELD -> AREA -> FULL-BOX-TICKMARKS"] ...
       [PARTIAL-TUBE | "-> &FIELD -> AREA -> FULL-TUBE"] ...
       [PARTIAL-PLANES | "-> &FIELD -> AREA -> FULL-PLANES"] ...
       ["-> &FIELD -> AREA -> SPLIT-INTERSECTING-PLANES" | NOSPLIT-INTERSECTING-PLANES] ...
       [NOSORT-PLANES | "-> &FIELD -> AREA -> SORT-PLANES"] ...
       ["-> &FIELD -> AREA -> OUTLINE" | NOOUTLINE] ...
       ["-> &FIELD -> AREA -> PLOT-MAP" | NOPLOT-MAP] ...
       [NOSTEP | "-> &FIELD -> AREA -> STEP"]
!W
Example: !W
  AREA -1 -1 1 1
!W
3 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,\φ) and the range in z is left unchanged. Field plots are made only over the part of the viewing "-> &FIELD -> AREA -> 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.] 3 plane The VIEW argument enables you to define the viewing plane. The "-> &FIELD -> AREA -> plane -> coordinates" in this plane can to some extent be influenced by specifying a rotation "-> &FIELD -> AREA -> angle". 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-FIELD "-> &FIELD -> PLOT-FIELD -> SURFACE", PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> VECTOR" and PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> 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. Examples: !W
  area view x+2*y+3*z=5
  area view y=z
  area view y=0 rotate 90
!W
[The default setting is Z=0.] 4 coordinates The coordinates system in the viewing "-> &FIELD -> AREA -> 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: !W
  a*x + b*y + c*z = d
!W
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: !W
  Origin = N . d / (a\² + b\² + c\²)
!W
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\ \×\ U and in the second case U\ =\ V\ \×\ N. These coordinates are chosen such that x is the first coordinate axis for a view in the y=0 plane and y the second coordinate axis for the x=0 plane. The default axes can be rotated by user specified "-> &FIELD -> AREA -> angle". 3 angle If the default "-> &FIELD -> AREA -> plane -> coordinates" in the viewing "-> &FIELD -> AREA -> plane" do not suit you, then you can rotate these axes by an amount you specify with this keyword. This angle must not be specified with the X-Y, Y-Z, X-Z and R-PHI projections. The angle should be given in degrees. [Default rotation angle: 0\ \°.] 3 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 "-> &FIELD -> AREA -> PLOT-MAP" option is active. This type of plot consists of !Wul_start - the coordinate frame, using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - a coordinate grid, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - the planes, using the "-> graphics -> REPRESENTATION -> item -> PLANES" polyline representation; - the tube, using the "-> graphics -> REPRESENTATION -> item -> TUBE" polyline representation; - if "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in effect, then the wires use the "-> graphics -> REPRESENTATION -> item -> C-WIRES", "-> graphics -> REPRESENTATION -> item -> OTHER-WIRES", "-> graphics -> REPRESENTATION -> item -> P-WIRES" and "-> graphics -> REPRESENTATION -> item -> S-WIRES" polymarker representations, otherwise the "-> graphics -> REPRESENTATION -> item -> WIRES", fill area representation is used; - cross sections through the elements of the field map, if present and provided the "-> &FIELD -> AREA -> PLOT-MAP" option is on, using the "-> graphics -> REPRESENTATION -> item -> MATERIAL-1", "-> graphics -> REPRESENTATION -> item -> MATERIAL-2", "-> graphics -> REPRESENTATION -> item -> MATERIAL-3", "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and "-> graphics -> REPRESENTATION -> item -> MATERIAL-5" fill area representations. !Wul_end [This is the initial default for Cartesian cells and cells that have a tube, provided no VIEW is specified.] 3 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 "-> &FIELD -> AREA -> PLOT-MAP" option is active. Beware that the coordinate system used for this view is left-handed. Trajectories of particles in a magnetic field will therefore appear to bend counter-naturally. To obtain a right-handed view of the same "-> &FIELD -> AREA -> plane", use VIEW y=0 and request a "-> &FIELD -> AREA -> CUT" projection, optionally specifying a rotation "-> &FIELD -> AREA -> angle". This type of plot consists of !Wul_start - the coordinate frame, using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - a coordinate grid, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - cross sections through the elements of the field map, if present and provided the "-> &FIELD -> AREA -> PLOT-MAP" option is on, using the "-> graphics -> REPRESENTATION -> item -> MATERIAL-1", "-> graphics -> REPRESENTATION -> item -> MATERIAL-2", "-> graphics -> REPRESENTATION -> item -> MATERIAL-3", "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and "-> graphics -> REPRESENTATION -> item -> MATERIAL-5" fill area representations. !Wul_end [X-Y is default] 3 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 "-> &FIELD -> AREA -> PLOT-MAP" option is active. This type of plot consists of !Wul_start - the coordinate frame, using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - a coordinate grid, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - cross sections through the elements of the field map, if present and provided the "-> &FIELD -> AREA -> PLOT-MAP" option is on, using the "-> graphics -> REPRESENTATION -> item -> MATERIAL-1", "-> graphics -> REPRESENTATION -> item -> MATERIAL-2", "-> graphics -> REPRESENTATION -> item -> MATERIAL-3", "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and "-> graphics -> REPRESENTATION -> item -> MATERIAL-5" fill area representations. !Wul_end [X-Y is default] 3 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 !Wul_start - the coordinate frame, using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - a coordinate grid, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - the planes, using the "-> graphics -> REPRESENTATION -> item -> PLANES" polyline representation; - if "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in effect, then the wires use the "-> graphics -> REPRESENTATION -> item -> C-WIRES", "-> graphics -> REPRESENTATION -> item -> OTHER-WIRES", "-> graphics -> REPRESENTATION -> item -> P-WIRES" and "-> graphics -> REPRESENTATION -> item -> S-WIRES" polymarker representations, otherwise the "-> graphics -> REPRESENTATION -> item -> WIRES", fill area representation is used; !Wul_end [This is the default in polar cells.] 3 CUT Asks for a cut through the AREA in the location of the viewing "-> &FIELD -> AREA -> 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 "-> &FIELD -> AREA -> X-Y", "-> &FIELD -> AREA -> X-Z" or "-> &FIELD -> AREA -> Y-Z" options should be used. If on the other hand solids should be shown, then the 3D option might be preferable. If the "-> &FIELD -> AREA -> 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 !Wul_start - the square outline that encloses the projection of the "-> &FIELD -> AREA -> box", using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - the area of the coordinate system that is located outside the box, using the "-> graphics -> REPRESENTATION -> item -> OUTSIDE-AREA" fill area representation; - a grid of projected coordinates, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - the viewing "-> &FIELD -> AREA -> plane", using the "-> graphics -> REPRESENTATION -> item -> COMMENT" text representation; - the planes, using the "-> graphics -> REPRESENTATION -> item -> PLANES" polyline representation; - the tube, using the "-> graphics -> REPRESENTATION -> item -> TUBE" polyline representation; - cross sections through the wires and conductor solids, using the "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1", "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" fill area representations; - cross sections through the dielectric solids, using the "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1", "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" and "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" fill area representations; - the outlines of the wires, conductors and dielectric media using the "-> graphics -> REPRESENTATION -> item -> OUTLINE" polyline representation; - the materials of the field map, if present and provided the "-> &FIELD -> AREA -> PLOT-MAP" option is on, using the "-> graphics -> REPRESENTATION -> item -> MATERIAL-1", "-> graphics -> REPRESENTATION -> item -> MATERIAL-2", "-> graphics -> REPRESENTATION -> item -> MATERIAL-3", "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and "-> graphics -> REPRESENTATION -> item -> MATERIAL-5" fill area representations. !Wul_end !W A cut through the same GEM foil that illustrates the "-> &FIELD -> AREA -> 3D" view. Outlining is absent in this example. [CUT becomes the default if a viewing plane is defined in the same "-> &FIELD -> AREA" statement, unless 3D was set previously.] 3 3D Asks for a three dimensional impression of the chamber as seen along an axis normal to the viewing "-> &FIELD -> AREA -> 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 "-> &FIELD -> AREA -> light" source and the viewing "-> &FIELD -> AREA -> plane", on the "-> &FIELD -> AREA -> REFLECTED-FRACTION" and on the "-> &FIELD -> AREA -> ABSORBED-FRACTION" of the light. The various shades of each colour can be examined with the "-> graphics -> SHADING-MAP" graphics command. Elements of the field map are not shown with this projection, even if the "-> &FIELD -> AREA -> 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: !Wul_start - the 3 backmost panels, in various shades of the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" fill area representation; - the outlines of these panels, using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation; - a coordinate grid in each of these panels, using the "-> graphics -> REPRESENTATION -> item -> GRID" polyline representation, provided the "-> graphics -> OPTIONS -> GRID" graphics option is on; - the labels along the axes using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation; - the numbers along the axes using the "-> graphics -> REPRESENTATION -> item -> NUMBERS" text representation; - the title of the plot using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation; - the location of the light source using the "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS" polyline representation for the circle and the "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" polyline representation for the cross; - the planes, in various shades of the "-> graphics -> REPRESENTATION -> item -> PLANES" fill area representation and the polyline representation; - the tube, in various shades of the "-> graphics -> REPRESENTATION -> item -> TUBE" fill area representation and the polyline representation; - the strips of the planes and the tube, in various shades of the "-> graphics -> REPRESENTATION -> item -> STRIPS" fill area representation and the polyline representation; - the wires and conductor solids, in various shades of the "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1", "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3" fill area representations; - the dielectric solids, in various shades of the "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1", "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" and "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3" fill area representations; - the outlines of the wires, conductors and dielectric media using the "-> graphics -> REPRESENTATION -> item -> OUTLINE" polyline representation. !Wul_end !W A three dimensional view of a GEM foil with staggered holes. 3 NEBEM Requests a 3-dimensional view similar to the one produced in response to the "-> &FIELD -> AREA -> 3D" projection, but using the surface panels that have been transmitted to the neBEM program. In this view, the outside of the solids is shown in the same colour shades as in the 3D view, while the inside is shown with colour 8, usually red. The inside should only be visible if: !Wul_start - outer panels, or parts thereof, of a solid have been removed by the "-> &CELL -> CUT-SOLIDS" command, or - the "-> &CELL -> SOLIDS -> CYLINDER -> LIDS" option has been disabled for a cylinder, or - the "-> &FIELD -> AREA" "-> &FIELD -> AREA -> box" cuts through a solid, or - the device is periodic, in which case redundant panels on periodicity boundaries are automatically removed for reasons of efficiency. !Wul_end This option is valid only when neBEM is used to calculate the field. [Intended for debugging purposes.] 3 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: !Wul_start - by reflection of light from the surface in the direction of the observer Reflected light is assumed to be best visible when the normal vector of the panel is nearly equal to half the sum of the viewing direction and the light direction. A tolerance of 18\° (1\ \σ) is applied. - by diffuse scattering of light at a surface A surface illuminated by scattering is assumed visible if its normal vector and the viewing direction are less than 90\° apart. Diffusely scattered light is assumed to be fully random in direction. Surfaces on which the light falls with nearly normal incidence, are illuminated more (a Gaussian weighting with a 60\°\ \σ is assumed). !Wul_end 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: !Wul_start - the location of the light source, see "-> &FIELD -> AREA -> LIGHT-ORIGIN"; - the fraction of light that is lost, see "-> &FIELD -> AREA -> ABSORBED-FRACTION"; - the sharing between reflection and scattering, see "-> &FIELD -> AREA -> REFLECTED-FRACTION"; - the number of shades that are to be used, see "-> &FIELD -> AREA -> COLOURS". !Wul_end Parts of panels that are hidden behind others are removed, see "-> &FIELD -> AREA -> SPLIT-INTERSECTING-PLANES". 3 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 \φ and \θ, both in degrees. [Default is 30\° for \θ and \φ.] 3 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\ %] 3 ABSORBED-FRACTION Specifies how much of the incoming light is lost by absorption at the surface. Expressed as a percentage. [Default: 3\ %] 3 COLOURS Sets the number of shades of every colour that are used. The shades can be examined with the "-> graphics -> SHADING-MAP" graphics instructions. [Default: 10] 3 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.] 3 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. 3 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. 3 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 acceptable. In rare cases, an reasonable result can be obtained with the "-> &FIELD -> AREA -> 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 "-> OPTIONS -> DUMP-ON-GRAPHICS-ERROR -> PLASPL" procedure. [This option is meaningful only with 3D impressions, where the option is on by default.] 3 SORT-PLANES As a slightly faster alternative to "-> &FIELD -> AREA -> 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 "-> &FIELD -> AREA -> SPLIT-INTERSECTING-PLANES" procedure fails partially. [The option is off by default.] 3 OUTLINE Requests the outer edges of the solids to be emphasised with a line. Meaningful with "-> &FIELD -> AREA -> 3D" plots. Can also be used with "-> &FIELD -> AREA -> 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 "-> graphics -> REPRESENTATION -> item -> OUTLINE" representation. [Outlines are by default not drawn.] 3 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 "-> &CELL -> 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 "-> graphics -> REPRESENTATION -> item -> MATERIAL-1". The medium with the next highest dielectric constant with "-> graphics -> REPRESENTATION -> item -> MATERIAL-2" etc. The drift medium is never shown. Elements of a 2D field map are only shown in "-> &FIELD -> AREA -> X-Y" views and in "-> &FIELD -> AREA -> CUT" views at a constant z. The cross sections of the viewing "-> &FIELD -> AREA -> plane" with the elements of a 3D field map are shown in "-> &FIELD -> AREA -> X-Y", "-> &FIELD -> AREA -> X-Z", "-> &FIELD -> AREA -> Y-Z" and "-> &FIELD -> AREA -> CUT" views, but not in "-> &FIELD -> AREA -> 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 "-> &CELL -> SOLIDS" command. SOLIDS doesn't interfere with PLOT-MAP. This option can also be switched on or off with the "-> &CELL -> FIELD-MAP -> PLOT-MAP" option of the "-> &CELL -> FIELD-MAP" command. [This option is by default on if the dielectric constants are known.] 3 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.] 2 CHECK Checks the following aspects of the field calculations: !Wul_start - verifies that the potential near the wires agrees with the potentials specified with the "-> &CELL -> ROWS" statement and that the wire charges agree with the field integrals around the wires; - verifies that the potential near the planes and the tube wall agrees with the potentials specified with the "-> &CELL -> PLANE" and "-> &CELL -> TUBE" statements; - checks that the divergence of the electric field is zero and that the potential equals the gradient of the electric field. !Wul_end 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. The CHECK command is not meant to be used with finite element field maps. Even the MAXWELL option is not particularly useful since finite element fields are, by construction, not gradient-free. The finite element programs that are most commonly used with Garfield represent their potential as a 2nd order polynomials. Such potentials are gradient-free only if one imposes constraints on the coefficients, something that is in general not done. The finite element programs themselves are much better equipped to evaluate the quality of their field maps. The CHECK command works in the z=0 plane and ignores the VIEW part of the AREA command - this is justified since chambers that are made of wires, planes and periodicity do not have structure in the z-direction. This point will have to be revisited when 3D point charges are introduced. Format: !W
  CHECK ["-> &FIELD -> CHECK -> WIRES"] ...
             [EPSILON-WIRE "-> &FIELD -> CHECK -> \ε_wire"] ...
        ["-> &FIELD -> CHECK -> CHARGES"] ...
        ["-> &FIELD -> CHECK -> PLANES"] ...
        ["-> &FIELD -> CHECK -> TUBE"] ...
        ["-> &FIELD -> CHECK -> MAXWELL"] ...
             [BINS "-> &FIELD -> CHECK -> bins"] ...
             [EPSILON-MAXWELL "-> &FIELD -> CHECK -> \ε_Maxwell"] ...
             [PRINT | NOPRINT] ...
             [PLOT | NOPLOT] ...
        ["-> &FIELD -> CHECK -> FULL"] ...
        [NOKEEP-RESULTS | "-> &FIELD -> CHECK -> KEEP-RESULTS"]
!W
Example: !W
  CH WIRE BINS 50
!W
(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.) 3 bins The number of bins in the histograms produced by the "-> &FIELD -> CHECK -> MAXWELL" option. By default: 100\ bins. 3 \ε_Maxwell The \&epsilon used to compute differentials when comparing dV/dx and -Ex. This parameter is by default set to 10\-3\. 3 \ε_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 10\-5\. 3 FULL Switches on all four options: "-> &FIELD -> CHECK -> MAXWELL", "-> &FIELD -> CHECK -> PLANES", "-> &FIELD -> CHECK -> TUBE" and "-> &FIELD -> CHECK -> WIRES". 3 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 "-> &FIELD -> CHECK -> KEEP-RESULTS" option. 3 PLANES Compares the potential given to the planes with the potential calculated near the field. 3 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. 3 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 which is useful when determining the range of electric fields for which transport quantities are needed. If you wish to store these results in global variables, then use the "-> &FIELD -> CHECK -> KEEP-RESULTS" option. 3 CHARGES Verifies that the net flux of the electric field around the 3-dimensional charges matches the charge of these objects. 3 KEEP-RESULTS When this option is selected, the surface field and potential on the selected wires are stored as EX_n, EY_n, E_n, V_n and PHI_n, all of which are of type "-> algebra -> variables -> types -> Matrix", and where "n" is the wire number Also, the "-> algebra -> variables -> types -> Histogram"s from the "-> &FIELD -> CHECK -> MAXWELL" option are kept under the names EX_ERROR, EY_ERROR, EZ_ERROR, DIV_E, DIV_B. In case these global variables are already in use, then their original contents will be lost after CHECK has executed. You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or in a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. [The output is not kept by default.] 2 GRID Sets the number of grid points in x (or r) and y (or \φ) used to produce the plots and tables. In the field section, the grid determines the following: !Wul_start - the density of vectors in PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> VECTOR" plots; - the density of the search grid when using PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> CONTOUR"; - the number of sampling points for PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> HISTOGRAM"; - the mesh in 3-dimensional plots made with PLOT-FIELD "-> &FIELD -> PLOT-FIELD -> SURFACE"; - the density of the grid on which "-> &FIELD -> PRINT" shows field values; - the number of points in which the CHECK "-> &FIELD -> CHECK -> MAXWELL" command verifies the divergence of the field and the compatibility of the potential and the field; !Wul_end The grid is common to all sections. Format: !W
  GRID  "-> &FIELD -> GRID -> number"_of_steps_in_x  [number_of_steps_in_y]
!W
Example: !W
  GRID 50
!W
3 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 \φ) spacing. [Default is 25 for both.] 2 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. Dipole terms are available in Garfield for a few potential types via the "-> &CELL -> OPTIONS -> DIPOLE-TERMS" option. The absence of dipole terms for the remaining potential types, just like the absence of quadrupole etc. potentials in Garfield, is not a fundamental limitation. Such potentials can be added on request. Format: !W
  MULTIPOLE-MOMENTS ...
       WIRE "-> &FIELD -> MULTIPOLE-MOMENTS -> wire" ...
       [ORDER "-> &FIELD -> MULTIPOLE-MOMENTS -> order"] ...
       [RADIUS "-> &FIELD -> MULTIPOLE-MOMENTS -> r"] ...
       [NOPLOT | "-> &FIELD -> MULTIPOLE-MOMENTS -> PLOT"] ... 
       [NOPRINT | "-> &FIELD -> MULTIPOLE-MOMENTS -> PRINT"] ...
       [EPSILON "-> &FIELD -> MULTIPOLE-MOMENTS -> \ε"] ...
       [ITERATE-MAXIMUM "-> &FIELD -> MULTIPOLE-MOMENTS -> iter"]
!W
Example: !W
  MULTIPOLE WIRE 1 PLOT
!W
Will plot the multipole moments up to order 4 for wire 1. 3 wire Number of the wire for which the multipole decomposition must be done. [No default.] 3 order Order of the highest multipole moment. Dipole moments are computed for ORDER=1 and higher, quadrupole moments for ORDER=2 and higher etc. [Default: 4.] 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.] 3 \ε The 'small number' used by the fitting routine to calculate the covariance matrix. [Default: 10\-4\.] 3 iter The maximum number of iterations that the fitting routine may do. [Default: 20.] 3 PLOT Requests a plot of the potential around the wire and of each of the terms in which it has been decomposed. The following representations are used: !Wul_start - "-> graphics -> REPRESENTATION -> item -> FUNCTION-1": potential on the surface of the wire; - "-> graphics -> REPRESENTATION -> item -> FUNCTION-2": multipole fit to the potential around the wire; - "-> graphics -> REPRESENTATION -> item -> FUNCTION-3": the various multipole terms - the terms are easy tell apart by counting the number of maxima and minima, with the dipole term having just one of each, the quadrupole two etc. !Wul_end [This plot is by default not made.] 3 PRINT Requests information about the fitting process be printed. [This information is by default not printed.] 2 OPTIONS Sets field related as well as top level "-> OPTIONS". Format: !W
  OPTIONS [NOCHECK-MAP-INDICES | "-> &FIELD -> OPTIONS -> CHECK-MAP-INDICES"] ...
          ["-> &FIELD -> OPTIONS -> CONTOUR-ALL-MEDIA" | "-> &FIELD -> OPTIONS -> CONTOUR-DRIFT-MEDIUM"] ...
          [NOWIRE-MARKERS | "-> &FIELD -> OPTIONS -> WIRE-MARKERS"]
!W
Example: !W
  opt check-map contour-drift
!W
3 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.] 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.] 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.] 3 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 "-> &CELL -> OPTIONS -> WIRE-MARKERS" option in the cell section. 2 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: !W
  PLOT-FIELD ["-> &FIELD -> PLOT-FIELD -> CONTOUR" [f1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                             [N n] ...
                             [LABELS | NOLABELS] ] ...
             ["-> &FIELD -> PLOT-FIELD -> GRAPH" [f2]]    [ON f_curve] ...
                             [N n]] ...
                             [SCALE min max] ...
                             [NOPRINT | PRINT] ...
             ["-> &FIELD -> PLOT-FIELD -> HISTOGRAM" [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                             [BINS nbin]] ...
             ["-> &FIELD -> PLOT-FIELD -> SURFACE" [f4]   [ANGLES \φ \θ]] ...
             ["-> &FIELD -> PLOT-FIELD -> VECTOR" [f5 f6 [f7]]]
!W
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: !W
  PLOT HIST VECTOR SURF CONT
  PLOT CONTOUR RANGE 500 550
  PLOT GRAPH 'SIN X'
!W
(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.) 3 CONTOUR Produces a plot of the lines of equal function values. Contours are drawn in the part of the viewing "-> &FIELD -> AREA -> plane" that is located within the current "-> &FIELD -> AREA" box. The contours are labelled 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. Contours are plotted starting from their crossings with a regular "-> &FIELD -> GRID" covering the AREA. Very small contours are not found if the grid is course. It is therefore usually preferable to use a fine grid for contours, even though plotting the contours takes more time. You may also wish to optimise the "-> graphics -> CONTOUR-PARAMETERS", especially if your AREA is very small or highly non-isometric. The contours are drawn with the representation "-> graphics -> REPRESENTATION -> item -> CONTOUR-NORMAL" and are labelled with "-> graphics -> REPRESENTATION -> item -> 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.] 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 "-> &FIELD -> 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 "-> introduction -> quotes", e.g. !W
     on '"-> algebra -> functions -> cos"(pi*t),"-> algebra -> functions -> sin"(pi*t),0'
!W
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. Re-routing 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.] 3 HISTOGRAM The function is sampled over a "-> &FIELD -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &FIELD -> 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 "-> Call -> BOOK_HISTOGRAM -> options -> 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.] 3 SURFACE The function is sampled over a "-> &FIELD -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &FIELD -> AREA" box. The function values are presented as a three dimensional plot. The plot is first rotated by \φ degrees around the z-axis and then tilted by \θ 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\°. The viewing angles are remembered from one call to the next.] 3 VECTOR This plot shows the flow of a 3-vector sampled over a "-> &FIELD -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &FIELD -> AREA" box. The vectors are projected onto the viewing plane. The z-component is set to 0, if not explicitly 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" representation. The appearance of the arrow is influence by the "-> graphics -> ARROW-TIP-ANGLE" and "-> graphics -> ARROW-TIP-LENGTH" settings. [The default functions are EX, EY, EZ.] 3 function All functions (f1, f2 ... f7) should be expressions in terms of the following quantities: !Wtable_start !T+P + + . ----------------------------------------------------------------------- Name Meaning Unit ----------------------------------------------------------------------- X or R x- or r-Coordinate of a point cm Y or PHI y- or \φ-Coordinate of a point cm or degrees Z z-Coordinate of a point cm EX or ER x- or r-Component of the electric field V/cm EY or EPHI x- or \φ-Component of the electric field V/cm EZ z-Component of the electric field V/cm E Norm of the electric field V/cm V Electrostatic potential V BX x-Component of the magnetic field 100 G = 0.01 T BY y-Component of the magnetic field 100 G = 0.01 T BZ z-Component of the magnetic field 100 G = 0.01 T B Norm of the magnetic field 100 G = 0.01 T ----------------------------------------------------------------------- !Wtable_end Note: The variables BX and BY should not be used with cells that have been described in polar coordinates. 2 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. "-> &FIELD -> 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 10\×10 block of points on the current "-> &FIELD -> GRID". Format: !W
  PRINT f1 f2 ...
!W
Example: !W
  PR EX, EY, E, V
!W
3 functions All functions should be expressions in terms of the following quantities: !Wtable_start !T+P + . -------------------------------------------------------------------------- Name Meaning -------------------------------------------------------------------------- X or R x- or r-Coordinate of a point Y or PHI y- or \φ-Coordinate of a point EX or ER x- or r-Component of the electric field at (x/r,y/\φ) EY or EPHI x- or \φ-Component of the electric field at (x/r,y/\φ) E Norm of the electric field at (x/r,y/\φ) BX x-Component of the magnetic field at (x/r,y/\φ) BY y-Component of the magnetic field at (x/r,y/\φ) BZ z-Component of the magnetic field at (x/r,y/\φ) B Norm of the magnetic field at (x/r,y/\φ) V Electrostatic potential at (x/r,y/\φ) -------------------------------------------------------------------------- !Wtable_end Note: The variables BX and BY should not be used with cells that have been described in polar coordinates. 2 SAMPLE Evaluates and prints the field at a single point. This instruction was used for debugging, but is now superseded by the procedure calls "-> Call -> ELECTRIC_FIELD" and "-> Call -> ELECTRIC_FIELD_3". Format: !W
  SAMPLE x y
!W
Example: !W
  SAMPLE 0.5 0.5
!W
2 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 selection determines which wires are checked by "-> &FIELD -> CHECK". The grouping is of no importance. Selection of other electrodes than wires has no effect. Format: !W
  SELECT "-> &FIELD -> SELECT -> selection"
!W
Example: !W
  SEL (1 S) 2 F
!W
(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.) 3 selection The selection string can consist of the following elements: !Wul_start - wire "-> &CELL -> ROWS -> label"s, - "-> &CELL -> PLANE -> label"s of complete planes, - "-> &CELL -> PLANE -> strip_label"s for parts of planes, - the tube "-> &CELL -> TUBE -> label", - "-> &CELL -> TUBE -> strip_label"s for the tube, - "-> &CELL -> FIELD-MAP -> FILES -> label"s of weighting field maps, - labels of "-> &CELL -> SOLIDS", - numeric identifications of wires, planes, tube and field maps, - "-> introduction -> separators" (blank, comma, colon and equal sign), - round "-> introduction -> brackets". !Wul_end A wire, a plane, the tube, a strip 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 -> SIGNAL" command, otherwise the signal is classified as "cross induced" - and it would not be computed unless the "-> &SIGNAL -> SIGNAL -> 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" and DRIFT "-> &DRIFT -> 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: !Wtable_start !T+P + . --------------------------------------------- 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 --------------------------------------------- !Wtable_end [An initial selection is made in which all electrodes with an "S" label are assigned to a group of their own.] 2 TIME Performs field evaluation at random locations distributed over the current AREA and times them. Format: !W
  TIME ["-> &FIELD -> TIME -> n"]
!W
Example: !W
  TIME 10000
!W
3 n Number of times the field evaluation is to be repeated. [Default: 1000\ times] 2 TRACK Defines the line over which the "-> &FIELD -> PLOT-FIELD -> GRAPH" is made by the "-> &FIELD -> 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 "-> &DRIFT -> TRACK" command in the drift section. Example: !W
  TR -1 -1 -1 1
!W
1 &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. 2 overview The instructions of the drift section fall in 4 categories: !Wul_start - setting various parameters - calibration - display of drift behaviour - service instructions !Wul_end 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: !Wtable_start !T+IP + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end Calibration: !Wtable_start !T+IP + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end Display drift behaviour: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ CLUSTERING-HISTOGRAMS Makes histograms of the cluster statistics DRIFT Plots drift-lines and isochrons 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 ------------------------------------------------------------------------ !Wtable_end Service instructions: !Wtable_start !T+IP + . ------------------------------------------------------------------------ Command Short description ------------------------------------------------------------------------ GET-TRACK Retrieves a prepared track from a file PREPARE-TRACK Prepares a track of interpolation WRITE-ISOCHRONS Writes the set of isochrons to a file WRITE-TRACK Writes a prepared track to a file ------------------------------------------------------------------------ !Wtable_end Note: There are procedures that perform drift related tasks: "-> Call -> AVALANCHE", "-> Call -> DRIFT_ELECTRON", "-> Call -> DRIFT_ELECTRON_3", "-> Call -> DRIFT_MC_ELECTRON", "-> Call -> DRIFT_POSITRON", "-> Call -> DRIFT_POSITRON_3", "-> Call -> DRIFT_MC_POSITRON", "-> Call -> DRIFT_ION", "-> Call -> DRIFT_ION_3", "-> Call -> DRIFT_MC_ION", "-> Call -> DRIFT_MC_NEGATIVE_ION", "-> Call -> DRIFT_NEGATIVE_ION", "-> Call -> DRIFT_NEGATIVE_ION_3", "-> Call -> DRIFT_INFORMATION", "-> Call -> GET_CLUSTER", "-> Call -> GET_DRIFT_LINE", "-> Call -> NEW_TRACK", "-> Call -> PLOT_DRIFT_AREA", "-> Call -> PLOT_DRIFT_LINE", "-> Call -> PLOT_TRACK", "-> Call -> PRINT_DRIFT_LINE" and "-> Call -> RND_MULTIPLICATION". The "-> Call -> FIT_GAUSSIAN" procedure can be of use when studying the output of the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" instruction. 2 methods Garfield currently has 4 different integration techniques: !Wul_start - "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg"; - "-> &DRIFT -> methods -> Monte_Carlo"; - "-> &DRIFT -> methods -> microscopic" and - vacuum. !Wul_end !W The above plot illustrates 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: !W
  "-> &DRIFT -> area" -0.11 -0.11 0.11 0.11
  int-par mc-dist-int 0.001
  Call "-> Call -> plot_drift_area"
  For i From 1 To 20 Do
     Call "-> Call -> drift_mc_electron"(0.005,0.09,0)
     Call "-> Call -> plot_drift_line"
  Enddo
  Call "-> Call -> drift_electron"(0.005,-0.09)
  Call "-> Call -> plot_drift_line"
  Call "-> Call -> plot_end"
!W
3 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 "-> &GAS -> TABLE" and "-> &GAS -> ADD" gas section commands. Electron velocities can in addition be computed with "-> &GAS -> MAGBOLTZ" and "-> &GAS -> 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 local velocity. In vacuum, particles will follow a spiraling trajectory. In chamber gases however, both electrons and ions undergo frequent scattering as a result of which they move in a straight line. This motion can be described in 3 ways in Garfield: !Wul_start - Programs like Magboltz compute the velocity vector in E and B fields at random relative orientations. Garfield asks Magboltz to compute velocity vectors on a grid of E, B and angle(E,B) values, and interpolates the required vectors in the table. - Experimental data exists for the angle between the line of motion and the E field vector, an angle usually known as Lorentz angle. This angle can be entered by means of "-> &GAS -> TABLE -> LORENTZ-ANGLE". Since the Lorentz angle is defined for perpendicular E and B fields, Garfield uses the angle to compute a drift vector such that: !Wul_start - the angle between the drift velocity vector and E equals the tabulated Lorentz angle for the local electric and magnetic field; - the drift velocity vector is located in a plane spanned by E and E\×B; - the norm of the vector equals the tabulated velocity entered with "-> &GAS -> TABLE -> DRIFT-VELOCITY". !Wul_end - If neither complete vectors nor Lorentz angles for electrons are present in the gas tables, then the drift velocity vector is computed with the Langevin formula: !W
            \μ       /                          \\
    v = ---------- | E  +  \μ E\×B  +  \μ\² B (E.B) |
        1 + (\μ B)\²  \\                          /
!W
where \μ stands for the mobility with the sign of the charge. I.e. \μ is negative for electrons. The mobility is computed by dividing the velocity entered via "-> &GAS -> TABLE -> DRIFT-VELOCITY" by the electric field E. !Wul_end Since the Lorentz angle for ions can currently not be entered in the gas tables, the latter formula is always used for ions. 3 Runge_Kutta_Fehlberg Runge Kutta Fehlberg integration is initialised with !Wul_start - a starting point and the "-> &DRIFT -> methods -> velocity" vector (velocity for short) there; - a time step, conservatively set to the requested accuracy divided by the drift velocity at the starting point. !Wul_end The method iterates over the following steps: !Wol_start 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: !Wul_start - z\2\, accurate to 2nd order; - z\3\, accurate to 3rd order. !Wul_end 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> accuracy": !W
                 accuracy
     dt' =  dt \√ ---------
                 |z\2\ - z\3\|
!W
3. The step is repeated if: !Wul_start - the time step shrinks by more than a factor 5; - the step size exceeds the "-> &DRIFT -> INTEGRATION-PARAMETERS -> maximum_step" length allowed. !Wul_end 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. !Wol_end The iteration ends when any of the following conditions is satisfied: !Wul_start - The particle is traced to the nearest electrode if: !Wul_start + it enters in the attraction zone of a wire (see "-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS"); + the evaluation of z\2\ or z\3\ required a point inside an electrode; + the step went through a wire or across a plane. !Wul_end - The calculations are stopped if the number of steps reaches the maximum number of steps allowed. - The calculations are abandoned if: !Wul_start + kink rejection ("-> &DRIFT -> INTEGRATION-PARAMETERS -> REJECT-KINKS") is in effect and there is a kink of more than 90\° in the drift-line; + the step size drops below the requested "-> &DRIFT -> INTEGRATION-PARAMETERS -> accuracy"; + the velocity becomes zero or less, usually because the gas tables do not extend to the electric fields encountered near the electrodes; + a particle moves away from an electrode that is charged such that it should attract the particle. !Wul_end !Wul_end 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. 3 Monte_Carlo The Monte Carlo drift-line integration method is initialised by: !Wul_start - a starting point and the drift "-> &DRIFT -> methods -> velocity" vector there; - a time "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size", which is derived from: !Wul_start + a user specified time step; + a user specified distance step, converted to a time step by dividing by the norm of the velocity vector; + an estimate of the time between 2 collisions according to: !W
      \½ m v\² = t E
!W
then drawing an exponentially distributed time interval with the collision time as mean and multiplying this with a user specified number of collisions to be skipped. !Wul_end !Wul_end The method iterates over the following steps: !Wol_start 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. !Wol_end The iteration ends when any of the following conditions is satisfied: !Wul_start - The particle is traced to the nearest electrode if: !Wul_start + it enters in the attraction zone of a wire (see "-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS"); + the step entered an electrode; + the step went through a wire or across a plane. !Wul_end - The calculations are stopped if the number of steps reaches the maximum number of steps allowed. - The calculations are abandoned if: !Wul_start + the velocity becomes zero; + a particle moves away from an electrode that is charged such that it should attract the particle. !Wul_end !Wul_end 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 preferred 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. 3 microscopic Electron tracking at the molecular level using Monte Carlo techniques. This method relies heavily on the Magboltz procedures and should give results which are statistically compatible with Magboltz tables. Between collisions with gas molecules, the electron follows a vacuum trajectory. The path length between collisions is drawn from an exponential distribution around the mean free path that corresponds to the electron energy. The null-collision technique [H.R. Skullerud, Brit. J. Appl. Phys. series 2 volume 1 (1968) 1567-1577] is used to correct for the variations of the mean free path as a result of the change in electron kinetic energy between collisions. Each collision is classified as one of the following with one of the molecule species present in the gas: !Wul_start - elastic: energy is neither lost nor gained; - inelastic: the electron excites a gas molecule and loses energy while in the process; - super-elastic: interactions in which the electron gains energy; - attachment: loss of the electron through attachment; - ionisation: production of an additional electron. !Wul_end The choice is made according to the relative cross sections of these processes at the energy of the electron just prior to the collision. Magboltz contains for each gas "-> &GAS -> MAGBOLTZ -> ingredient" separate cross sections for each type of interaction. It is not unusual that several tens or even hundreds of processes take part. Procedures which perform microscopic tracking include "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" and "-> Call -> MICROSCOPIC_AVALANCHE". 3 diffusion Diffusion is primarily a spatial effect. While a particle drifts, it will on average follow the drift "-> &DRIFT -> methods -> 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: !Wul_start - the spread in arrival time over a given drift path due to longitudinal diffusion only; - the spread in arrival time over a given drift path due to transverse and longitudinal diffusion, estimated by propagating a probability cloud over the path; - the spread in arrival point and time due to both longitudinal and transverse diffusion using a Monte Carlo technique. !Wul_end 4 longitudinal Integration of the longitudinal coefficient alone is normally only performed when the drift-line has been computed with the "-> &DRIFT -> methods -> 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 "-> &GAS -> MAGBOLTZ", then transverse diffusion coefficients are stored - unless they have subsequently been deleted with the "-> &GAS -> RESET" command of the gas section. Such integration can explicitly be requested by calling procedures like "-> Call -> DRIFT_ELECTRON" after having deleted the transverse diffusion data, if needed. Since the "-> &DRIFT -> DRIFT" command by default uses Runge-Kutta-Fehlberg integration, the diffusion "-> &DRIFT -> DRIFT -> TRACK -> graph" made by the DRIFT "-> &DRIFT -> 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: !W
  spread\² = \∫ (\σ/speed)\² dz
!W
The integration is performed using the Newton-Raphson technique over each step of the drift-line, repeatedly bisecting a step until either the maximum "-> &DRIFT -> INTEGRATION-PARAMETERS -> stack" depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction "-> &DRIFT -> INTEGRATION-PARAMETERS -> \ε" of the trapezoidal estimate without bisection of the integral over the entire path. 4 cloud If a drift-line has been computed with the "-> &DRIFT -> methods -> 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 \δ-distribution at the starting point, the cloud is adjusted at each step according to the following phenomena: !Wul_start - additional transverse and longitudinal diffusion at each step, according to the local diffusion coefficients; - longitudinal stretch due to acceleration and deceleration of the electrons along the central drift-line; - transverse compression due to convergence of drift-lines neighbouring to the central drift-line; - alignment of one main axis with the central direction of motion. !Wul_end The cloud is considered Gaussian at every stage. When the centre of the cloud comes closer than "-> &DRIFT -> INTEGRATION-PARAMETERS -> ncloud" wire radii to a wire, the cloud is projected onto the wire using one of several "-> &DRIFT -> INTEGRATION-PARAMETERS -> method"s. 4 Monte_Carlo "-> &DRIFT -> methods -> Monte_Carlo" integration includes a simulation of the diffusion process. 3 multiplication The mean gas multiplication over a drift path is estimated as the exponentiated integral of the Townsend coefficient over the path: !W
  M = e\\∫ \α dz\
!W
The integration is performed using the Newton-Raphson technique over each step of the drift-line, repeatedly bisecting a step until either the maximum "-> &DRIFT -> INTEGRATION-PARAMETERS -> stack" depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction "-> &DRIFT -> INTEGRATION-PARAMETERS -> \ε" 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 "-> &DRIFT -> methods -> Monte_Carlo" technique is larger than the integral over a drift path from the same point computed with the "-> &DRIFT -> methods -> 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 which are suitable for use with an Runge-Kutta path. The "-> &DRIFT -> INTEGRATION-PARAMETERS -> PROJECTED-PATH-INTEGRATION" integration parameter can in certain contexts be used to reduce the step size dependence of the integral over Monte Carlo paths. Attachment, even at a rate which is orders of magnitude smaller than the gain, profoundly modifies the avalanche fluctuations. Usually, the effect of combined gain and attachment is a loss of energy resolution. The reason for this effect is that the attachment rate, in many gas mixtures, exceeds the gain at the onset of the avalanche. Thus, there is a non-negligible probability that an electron is lost before it can start an avalanche while attachment after the avalanche has reached a certain size has virtually no effect anymore. Fluctuations of the avalanche size can be estimated by using the "-> Call -> AVALANCHE" and "-> Call -> RND_MULTIPLICATION" procedures. 3 attachment The attachment losses over a drift path are estimated as the exponentiated integral of the attachment coefficient over the path: !W
  L = e\- \∫ η dz\
!W
The integration is performed using the Newton-Raphson technique over each step of the drift-line, repeatedly bisecting a step until either the maximum "-> &DRIFT -> INTEGRATION-PARAMETERS -> stack" depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction "-> &DRIFT -> INTEGRATION-PARAMETERS -> \ε" 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 "-> &DRIFT -> methods -> Monte_Carlo" technique is larger than the integral over a drift path from the same point computed with the "-> &DRIFT -> methods -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> PROJECTED-PATH-INTEGRATION" integration parameter can in certain contexts be used to reduce the step size dependence of the integral over Monte Carlo paths. 3 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 "-> Call -> DRIFT_INFORMATION" procedure returns on request the status of the last drift-line that has been computed in either of these 2 formats. !Wtable_start !T+ +P RP . --------------------------------------------------------------------------------------- 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 Attached by a gas molecule Attached -7 Drift-line makes sharp kink Bend sharper than pi/2 -8 Electron energy too high Energy exceeds E_maximum -9 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 Below transport energy Below transport cut -16 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 --------------------------------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. The drift area is set with the "-> &DRIFT -> AREA" command. When magnetic fields are present, care should be taken to define an appropriate drift area in all 3 dimensions. 2. If a drift-line ends because the calculation requires too many steps, then usually either the integration "-> &DRIFT -> INTEGRATION-PARAMETERS -> accuracy" or the "-> &DRIFT -> INTEGRATION-PARAMETERS -> maximum_step" size are poorly chosen. The permitted maximum number of steps MXLIST is set at compilation time. 3. Faults can occur for a variety of reasons specific to the integration technique used (either "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" or "-> &DRIFT -> methods -> Monte_Carlo"). 4. The status "Bend sharper than pi/2" only occurs if the "-> &DRIFT -> INTEGRATION-PARAMETERS -> REJECT-KINKS" integration parameter has been switched on. 5. The status "Energy exceeds E_maximum" only occurs with "-> &DRIFT -> methods -> microscopic" electron tracing as a result of an incorrect choice of the "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum" parameter. 6. When a particle hits an electrode in a finite element field map, it will usually be declared to have "Left the mesh": finite element programs do not normally generate a mesh inside conductors. If "-> &CELL -> SOLIDS" have been defined, then Garfield will check whether the last point on the mesh is located inside a solid, in which case it will assign a status code accordingly. 7. The "X" in the status code for wires, replicas of wires and solids is replaced by the corresponding wire "-> &CELL -> ROWS -> label" or the corresponding solid label (see "-> &CELL -> SOLIDS"). "N" is replaced by the respective sequence number. 8. A further status code, "Started from a line or an edge" (numeric code -20), is used when the "-> &DRIFT -> DRIFT -> REVERSE-ISOCHRONS" option has not been used for plotting isochrons in "-> &DRIFT -> DRIFT -> EDGES" and "-> &DRIFT -> DRIFT -> TRACK" plots. This status code merely indicates that the particle started from an edge or from the track and it does not give information on the end point of the particle. 9. A status "Calculations abandoned" can correspond to any of a large number of situations. Examples include: zero electric field, zero electron velocity, step-size smaller than the "-> &DRIFT -> INTEGRATION-PARAMETERS -> accuracy", error computing the rotation matrices or divergence tensors used for Monte Carlo integration, difficulties terminating a drift-line on an electrode, internal inconsistencies. !Wol_end 2 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 "-> &FIELD -> AREA" command in the field section. 2 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 "-> &DRIFT -> XT-PLOT" for a comparison with related commands. Before issuing this command, you should take care of the following: !Wul_start - The drift "-> &DRIFT -> AREA" should be set sufficiently large that all points from which electrons can reach a selected electrode are inside. The viewing "-> &FIELD -> AREA -> plane" and the projection are not used by the present command - they can be set in a manner which facilitates examining the drift paths. - This command overwrites the geometrical track information but makes use of the clustering model. Since the default clustering model is not meaningful in the present context, the "-> &DRIFT -> TRACK" command should be used to select e.g. Heed clustering. - When using Heed clustering, ensure that the "-> &DRIFT -> INTEGRATION-PARAMETERS -> COMPUTE-IF-INTERPOLATION-FAILS" integration parameter is active. This command prepares an interpolation table for points on the track while Heed may generate ionisation electrons that are not located on the track (e.g. \δ-electrons). - Only selected electrodes are considered by this command. The "-> &DRIFT -> SELECT" command can be used to examine and modify the selection. Electrode grouping has no effect on the present command. - The "-> OPTIONS -> PROGRESS-PRINT" global option enables you to follow the progress of the calculations. - The "-> &DRIFT -> OPTIONS -> DRIFT-PLOT" option is of use to verify that the tracks cover the desired part of the chamber and that the electrons really reach the electrodes. !Wul_end By default, this command operates in the x-y "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plane", but it can also work in the y-z and z-x planes. The choice is controlled with the STEP and SCAN keywords. Another important argument is ELECTRON. Format: !W
  ARRIVAL-TIME-DISTRIBUTION ...
       [ELECTRON {"-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> electron" | LAST | ONE-BUT-LAST | ... }] ...
       [THRESHOLD "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> threshold"] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW" {"-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW -> AUTOMATIC" | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW -> FULL-RANGE" | tmin tmax }] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP" {X | Y | Z} ...
             ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP -> RANGE" umin umax] ...
             ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP -> INCREMENT" ustep]] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN" {X | Y | Z} ...
             ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN -> RANGE" vmin vmax] ...
             ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN -> ANGLE" phi]] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> OFFSET" w] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> LINES" lines] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DIFFUSION" | NODIFFUSION] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> ATTACHMENT" | NOATTACHMENT] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DATASET" "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DATASET -> file" ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DATASET -> member"]] [REMARK "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DATASET -> remark"] ...
       [BINS "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> bins"] ...
       [ITERATIONS "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> iterations"] ...
       [POLYNOMIAL-ORDER "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> order"] ...
       [NOKEEP-HISTOGRAMS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS"] ...
       [NOKEEP-RESULTS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-RESULTS"] ...
       [NOPLOT-ALL-ELECTRONS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plot_options -> PLOT-ALL-ELECTRONS"] ...
       [NOPLOT-SELECTED-ELECTRONS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plot_options -> PLOT-SELECTED-ELECTRONS"] ...
       [NOPRINT-ALL-ELECTRONS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> print_options -> PRINT-ALL-ELECTRONS"] ...
       [NOPRINT-SELECTED-ELECTRONS | "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> print_options -> PRINT-SELECTED-ELECTRONS"] ...
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plot_options -> PLOT-OVERVIEW" | NOPLOT-OVERVIEW]
       ["-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> print_options -> PRINT-OVERVIEW" | NOPRINT-OVERVIEW]
!W
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: !W
  "-> &DRIFT -> track" exponential
  arrival electron 5 last dataset "arrival/electron.5" thresh 0.8
!W
The track type is set to "-> &DRIFT -> TRACK -> 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 "-> &DRIFT -> TRACK -> 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. 3 plane This command works in either the x-y, the y-z or the z-x plane, optionally with a constant "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP -> INCREMENT". The axis which should serve as stepping axis is identified with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP" keyword. You can set the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP -> 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN -> ANGLE" to this axis, but will usually be parallel to it. The axis which should serve as stepping axis is identified with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN" keyword. Like for the stepping axis, You can limit the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN -> RANGE" of coordinates along the stepping axis. !W
!W !W
3 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.] 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.] 3 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: !Wul_start - specifying an explicit time window; - "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW -> AUTOMATIC", to request a time range determined by the first entries; - "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW -> FULL-RANGE", adopting the full time range of the track. !Wul_end 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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.] 4 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> bins" of the histograms. You should ensure that the number of track "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> iterations" is at least equal to half the number of bins. 4 FULL-RANGE 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-RANGE. 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. 3 STEP Determines, together with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN", the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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] 4 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 "-> &DRIFT -> AREA".] 4 INCREMENT The distance, measured along the stepping axis, between 2 tracks. [Default: approximately 5\ % of the stepping range.] 3 SCAN Determines, together with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> STEP", the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plane" in which the tracks will be located. Tracks are usually parallel to the scanning axis, or at a small "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> SCAN -> 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] 4 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> LINES" parameter is set to a high value. Moreover, considerable waste of CPU time occurs. [Default: the entire scanning range as given by "-> &DRIFT -> AREA".] 4 ANGLE The angle of the tracks with respect to the scanning-axis. [Default: initially 0\°. The angle that you set is kept as default for the next call.] 3 OFFSET By default, this command works in a "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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. 3 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. 3 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. 3 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 "-> &DRIFT -> LINES" parameter from the drift section.] 3 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.] 3 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 "-> Call -> FIT_GAUSSIAN" procedure, or by a user program after writing the histograms out with the "-> Call -> WRITE_HISTOGRAM" procedure. You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. [Default: histograms are not kept. The setting is kept across calls of ARRIVAL.] 3 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: !Wtable_start !T+P + + . ------------------------------------------------------------------- Global Description Type ------------------------------------------------------------------- [X|Y|Z]_ Distance from electrode Matrix MEAN_ mean time all electrons Matrix MEDIAN_ median time all electrons Matrix RMS_ RMS time all electrons Matrix MEAN_ mean time selected electron Matrix MEDIAN median time selected electron Matrix RMS_ RMS time selected electron Matrix E_ sequence # selected electron Number ------------------------------------------------------------------- !Wtable_end The string "" in the global variable name is set to 1 for the first selected electrode, 2 for the next etc. The string "" is an index that runs from 1 to the number of selected electrons. E_ 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 !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. [This option is not on by default, but its setting is remembered from one call to the next.] 3 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 ("-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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 are far from the mean. When specifying "-> &DRIFT -> TRACK -> 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.] 3 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.] 3 DATASET Requests output of a summary of the calculations to a dataset. [Dataset output is only done on request.] 4 file The name of the "-> dataset -> structure -> file" in which you wish to write the cell description. 4 member The name by which you will want to reference the "-> dataset -> structure -> member" when retrieving it. 4 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. Garfield uses by default a string specifying the electrode as remark for the member header. You may override this. 3 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. 4 PLOT-SELECTED-ELECTRONS Plots, for each track location, and for each selected electron: !Wul_start - an histogram of the time needed by the selected electron to reach the selected electrode; - an histogram of the origin of the selected electrons which reach the selected electrode. !Wul_end The time range of these histograms can be controlled with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW". You can request printouts of these histograms with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> print_options -> PRINT-SELECTED-ELECTRONS" or ask the histogram to stay in memory with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option. [These plots are not made by default. The default setting of each call is the setting of the previous call.] 4 PLOT-ALL-ELECTRONS Plots, for each track location: !Wul_start - an histogram with the distribution of the time needed by the electrons to reach the selected electrode; - an histogram of the origin of the electrons that reach the selected electrode - this distribution should be uniform over the acceptance of the electrode; - an histogram of the number of clusters generated on the entire track, covering the full scanning range, irrespective of whether the electrons from this cluster reach the selected electrode; - an histogram of the number of electrons that reach the selected electrode. !Wul_end The time range of these histograms can be controlled by "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW", provided you set an explicit time window. You can request printouts of these histograms with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> print_options -> PRINT-ALL-ELECTRONS" or ask the histogram to stay in memory with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option. [These plots are not made by default. The default setting of each call is the setting of the previous call.] 4 PLOT-OVERVIEW The PLOT-OVERVIEW option will ensure that the following 3 graphs are made: !Wol_start 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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 "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option can be used to store the histograms, more robust techniques can then be applied outside Garfield. !Wol_end In all plots, the all-electron graphs are plotted with the graphics representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", while the graphs for the selected electrons are plotted as "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". The results are kept in memory if you specify the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-RESULTS" option. [These plots are initially made by default. The default setting of each call is the setting of the previous call.] 3 print_options These options provide the same output as the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> 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.] 4 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 controlled with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW". You can request plots of these histograms with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plot_options -> PLOT-SELECTED-ELECTRONS" or ask the histogram to stay in memory with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option. [These printouts are not made by default. The default setting of each call is the setting of the previous call.] 4 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 controlled by "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> TIME-WINDOW", provided you set an explicit time window. You can request plots of these histograms with "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> plot_options -> PLOT-ALL-ELECTRONS" or ask the histogram to stay in memory with the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option. [These printouts are not made by default. The default setting of each call is the setting of the previous call.] 4 PRINT-OVERVIEW The option is accepted but has no effect. To obtain a printout, use "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> DATASET" output. 2 CLUSTERING-HISTOGRAMS Makes a set of histograms that show some aspects of the cluster statistics: !Wul_start - distance between electrons and track - number of clusters on the track - number of electrons on the track - energy in each cluster (if available) - total energy loss over the track (if available) !Wul_end These histograms are of use mainly if Heed is used to generate tracks. Keep the following in mind in this respect: !Wul_start - Heed, internally, doesn't have a concept of clusters. Most electrons that are deposited in the gas stem from "virtual gammas" which ionise a gas molecule by liberating electrons that may (\δ-electrons) or may not have enough energy to ionise further gas molecules. When you use the NO"-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" option of "-> &DRIFT -> TRACK", then all electrons that stem from a single virtual photon are placed at the location where the virtual photon was absorbed, thus creating a cluster. Such a cluster will usually be located very close to the track. With this option, the cluster size distribution is of interest, but the distance between track and electrons is meaningless. When you use the "-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" option of "-> &DRIFT -> TRACK", then each electron generated by Heed is dealt with as a cluster of size 1. The electrons will usually be located further from the track than the virtual photons. With this option, the cluster size distribution is of no interest, while the distribution between track and electrons reflects the range of \δ-electrons. - When using the "-> &DRIFT -> TRACK -> HEED -> MULTIPLE-SCATTERING" option of "-> &DRIFT -> TRACK", which is not default, then the distance between electrons and track is measured with respect to the average trajectory, i.e. the trajectory of the particle if there were no multiple scattering. !Wul_end Format: !W
  CLUSTERING-HISTOGRAMS ...
       [ITERATIONS  "-> &DRIFT -> CLUSTERING-HISTOGRAMS -> iter"] ...
       [BINS  "-> &DRIFT -> CLUSTERING-HISTOGRAMS -> 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 | "-> &DRIFT -> CLUSTERING-HISTOGRAMS -> KEEP-HISTOGRAMS"] ...
       ["-> &DRIFT -> CLUSTERING-HISTOGRAMS -> PLOT-HISTOGRAMS" | NOPLOT-HISTOGRAMS]
!W
3 iter The number of tracks to be generated. [By default 200] 3 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] 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.] 3 KEEP-HISTOGRAMS Requests the histograms to be kept in storage when the instruction has finished. The histograms will be called as follows: !Wtable_start !T+P + . ---------------------------------------------------------------- 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] ---------------------------------------------------------------- !Wtable_end You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> 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.] 3 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.] 2 DRIFT This instruction makes plots of electron and ion drift-lines and can also plot isochrons. The main choice is between the 5 kinds of starting points: !Wul_start - the "-> &DRIFT -> DRIFT -> EDGES" of the AREA; - the "-> &DRIFT -> DRIFT -> TRACK"; - the surface of selected "-> &DRIFT -> DRIFT -> SOLIDS" - the surface of selected "-> &DRIFT -> DRIFT -> WIRES"; - the "-> &DRIFT -> DRIFT -> ZEROES" of the electrostatic field. !Wul_end Each has a set of sub-options that should follow the EDGES, SOLIDS, WIRES, TRACK or ZEROES keyword. The other options should be placed at the end of the line. Format: !W
  DRIFT {"-> &DRIFT -> DRIFT -> EDGES"  [LEFT | NOTLEFT] ...
                [RIGHT | NOTRIGHT] ...
                [UP | NOTUP] ...
                [DOWN | NOTDOWN] ...
                [LINES "-> &DRIFT -> DRIFT -> EDGES -> lines"]                                    | ...
         "-> &DRIFT -> DRIFT -> TRACK"  [NOTIME-GRAPH | TIME-GRAPH] ...
                [NOVELOCITY-GRAPH | VELOCITY-GRAPH] ...
                [NODIFFUSION-GRAPH | DIFFUSION-GRAPH] ...
                [NOAVALANCHE-GRAPH | AVALANCHE-GRAPH] ...
                [NOFUNCTION-GRAPH | FUNCTION-GRAPH function] ...
                ["-> &DRIFT -> DRIFT -> TRACK -> MARKER" | SOLID]                                 | ...
         "-> &DRIFT -> DRIFT -> SOLIDS" [LINES "-> &DRIFT -> DRIFT -> SOLIDS -> lines"]                                    | ...
         "-> &DRIFT -> DRIFT -> WIRES"  [LINES "-> &DRIFT -> DRIFT -> WIRES -> lines"] ...
                [ANGLE-RANGE amin amax]                          | ...
         "-> &DRIFT -> DRIFT -> ZEROES"                                                    } ...

         ["-> &DRIFT -> DRIFT -> RUNGE-KUTTA-DRIFT" | "-> &DRIFT -> DRIFT -> MONTE-CARLO-DRIFT"] ...
         [NOISOCHRONS | "-> &DRIFT -> DRIFT -> ISOCHRONS" delta_t] ...
         ["-> &DRIFT -> DRIFT -> REVERSE-ISOCHRONS" | NOREVERSE-ISOCHRONS] ...
         ["-> &DRIFT -> DRIFT -> LINE-PLOT" | NOLINE-PLOT] ...
         [NOLINE-PRINT | "-> &DRIFT -> DRIFT -> LINE-PRINT"] ...
         ["-> &DRIFT -> DRIFT -> ELECTRON" | "-> &DRIFT -> DRIFT -> ION"] ...
         ["-> &DRIFT -> DRIFT -> NEGATIVE" | "-> &DRIFT -> DRIFT -> POSITIVE"]
!W
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: !W
  drift wires lines=25 isochrons 0.1 nol-pl
  drift track function-graph time+5*diffusion nol-pl l-pr
  drift zero
!W
(The first example will plot only a set of isochrons 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.) 3 EDGES Indicates that the drift-line calculation will begin at some of the boundaries of the drift area as set by "-> &DRIFT -> 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. Although other projections are permitted, this plot type is designed to work in the "-> &FIELD -> AREA -> X-Y" projection. !W

!W
!W !W

!WAn example of an EDGES drift-line plot, made with the following command: !W

!Wdrift edge left right notup notdown isochron 0.02
!W
!W
4 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. !Wtable_start !T+P +P + . ------------------------------------------------------- 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 -------------------------------------------------------- !Wtable_end [Default: HORIZONTAL.] 4 lines The number of drift-lines from each edge. A similar option exists for "-> &DRIFT -> DRIFT -> WIRES" and "-> &DRIFT -> DRIFT -> SOLIDS", but separate settings are maintained for each type of plot. Please note that this LINES option has no link anymore with the "-> &DRIFT -> 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.] 3 SOLIDS Requests that the electrons or ions start to drift from the intersection between the "-> &DRIFT -> SELECT"ed solids and the viewing "-> &FIELD -> AREA -> plane". You can control the number of drift-lines from each solid with the LINES keyword. "-> &DRIFT -> DRIFT -> ELECTRON"s 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 "-> &DRIFT -> DRIFT -> ION"s 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 "-> &DRIFT -> DRIFT -> POSITIVE" and "-> &DRIFT -> DRIFT -> NEGATIVE" options. !W

!W
!W !W

!WA SOLIDS drift-line plot made with a finite element field map of the !Wread-out structure of a TPC. !W

!Wdrift solid lines 50 ion positive contour 10 l-pl nol-pr
!W
!WSolids have been defined to represent the octagonal cathode, the gating !Wstructure (top of the figure) and the avalanche wire, at the origin. !WThe drift-lines start from the wire. !WThe plot has been made with the default isochron settings. !W
4 lines The number of drift-lines from each wire. A similar option exists for "-> &DRIFT -> DRIFT -> EDGES" and "-> &DRIFT -> DRIFT -> SOLIDS", but separate settings are maintained for each type of plot. Please note that this LINES option has no link anymore with the "-> &DRIFT -> LINES" command in the drift and signal sections. [Default: initially set to 20. The setting is remembered from one call to the next.] 3 WIRES Requests that the electrons with reversed charge or ions start to drift from the surfaces of the wires that have been "-> &DRIFT -> SELECT"ed. You can control the number of drift-lines from each wire with the LINES keyword. "-> &DRIFT -> DRIFT -> ELECTRON"s are not usually produced near the wires. If the absence of a B field component perpendicular to the E field, this command will drift the particles 'in reverse' so that the resulting plot shows the origin of all electrons that can end up on the wire. This interpretation does not apply should there be an E-perpendicular component of the B field. Since "-> &DRIFT -> DRIFT -> ION"s 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 "-> &DRIFT -> DRIFT -> POSITIVE" and "-> &DRIFT -> DRIFT -> NEGATIVE" options. !W

!W
!W !W

!WAn example of a WIRES drift-line plot, made with the following command: !W

!Wint-par iso-connect 0.1
!Wdrift wire lines 30 isochron 0.02
!W
!WThe distance over which isochron segments are connected has been !Wlimited in this example for clarity, !RSee "-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-CONNECTION-THRESHOLD" !Wfor more information on this. !W
4 angles Limits the angles under which electrons or ions leave the wire. The angle range should be specified in degrees. The x-axis is at 0\° while the y-axis is at 90\°. [Drift-lines are by default started from regularly spaced points around the wire. The setting is kept from one call to the next.] 4 lines The number of drift-lines from each wire. A similar option exists for "-> &DRIFT -> DRIFT -> EDGES" and "-> &DRIFT -> DRIFT -> SOLIDS", but separate settings are maintained for each type of plot. Please note that this LINES option has no link anymore with the "-> &DRIFT -> LINES" command in the drift and signal sections. [Default: initially set to 20. The setting is remembered from one call to the next.] 3 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 "-> &DRIFT -> TRACK" command: !Wul_start - electron or ion drift-lines from a user determined number of regularly spaced points along a track ("-> &DRIFT -> TRACK -> FIXED-NUMBER") - electron drift-lines from randomly distributed points along the track, including cluster formation ("-> &DRIFT -> TRACK -> EXPONENTIAL-SPACING") - electron drift-lines from the points where a particle traversing the chamber ionised the gas, including or not \δ- and Auger-electrons, photo ionisation and multiple scattering ("-> &DRIFT -> TRACK -> HEED") - electron or ion drift-lines at flux intervals ("-> &DRIFT -> TRACK -> EQUAL-FLUX-INTERVALS" or "-> &DRIFT -> TRACK -> CONSTANT-FLUX-INTERVALS") !Wul_end Although permitted, the "-> &DRIFT -> DRIFT -> ION" option is not meaningful when used together with Heed cluster generation. Unlike drifting from solids, edges or wires, DRIFT TRACK does not take its number of lines from a LINES keyword. !W

!W
!W !W

!WAn example of a TRACK drift-line plot, made with the following command: !W

!Wtrack -2.9 0.9 2.9 0.9 muon energy 1 GeV
!Wdrift track noisochrons
!W
!RThis figure shows a "-> &DRIFT -> TRACK -> HEED" simulation of a !W1 GeV muon in argon 50\ %, ethane 50\ % mixture. !W
4 graph The following graphs can be produced: !Wul_start - TIME-GRAPH: the drift time from the starting point on the track until the particle hits an electrode, leaves the drift area etc.; - VELOCITY-GRAPH: the ratio of the length of the drift path and the drift time; - DIFFUSION-GRAPH: the integrated diffusion computed by propagating a probability "-> &DRIFT -> methods -> diffusion -> cloud" along the drift path if both transverse and longitudinal diffusion coefficients are known, and computed integrating the "-> &DRIFT -> methods -> diffusion -> longitudinal" coefficient if the transverse coefficient is not known; - AVALANCHE-GRAPH: the "-> &DRIFT -> methods -> multiplication" over the drift path. !Wul_end The graphs can be customised with the FUNCTION-GRAPH option which takes as argument a function of the following parameters: !Wtable_start !T+P + R . ------------------------------------------------------------------- Variable Meaning Unit ------------------------------------------------------------------- AVALANCHE Gain over the drift path numeric LENGTH Drift-line path length cm DIFFUSION Integrated diffusion \μsec LOSS Survival probability numeric TIME Total drift time \μsec X_END or R_END x Or r at drift-line end cm Y_END or PHI_END y Or \φ at drift-line end cm or degrees Z_END z At drift-line end cm X_START or R_START x Or r at drift-line start cm Y_START or PHI_START y Or \φ at drift-line start cm or degrees Z_START z At drift-line start cm ------------------------------------------------------------------- !Wtable_end Further details on the survival probability can be found under the method used to integrate the "-> &DRIFT -> methods -> attachment" coefficients. Care should be taken that the "-> &DRIFT -> AREA" is chosen sufficiently large to let the particles reach their target. You may switch off the printing and plotting of both drift-lines and the plotting of isochrons 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 "-> &DRIFT -> DRIFT -> TRACK -> MARKER" and SOLID options. [By default, no graphs are produced. The set of requested graphs is remembered from one call to the next.] 4 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". SOLID means that points for drift-lines that reach the same end point are joined by straight line segments. The line type, width and colour are taken from polyline representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". Sections of the graph where the drift-lines reach a different end point are separated by vertical lines drawn with the "-> graphics -> REPRESENTATION -> item -> COMMENT" polyline representation. [The initial default is SOLID.] 3 ZEROES Indicates that the drift-line are calculated from the zeroes of the electrostatic field, both in the attracting and in the repelling directions. The "-> &DRIFT -> DRIFT -> ELECTRON"/"-> &DRIFT -> DRIFT -> ION" and "-> &DRIFT -> DRIFT -> POSITIVE"/"-> &DRIFT -> DRIFT -> 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. 3 RUNGE-KUTTA-DRIFT Requests the use of the "-> &DRIFT -> methods -> 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 controlling the accuracy are adjusted for chambers that are several centimetres large. When studying much smaller structures, at the micron scale, one may wish to request more "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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.] 3 MONTE-CARLO-DRIFT Requests "-> &DRIFT -> methods -> Monte_Carlo" calculation of a drift path, instead of a Runge Kutta Fehlberg integration. This option is particularly interesting used in conjunction with drifting from a "-> &DRIFT -> DRIFT -> TRACK" and on which clusters are generated with "-> &DRIFT -> TRACK -> HEED". When using this option, care has to be taken that the "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" has been set to a value appropriate to the chamber. [The initial default is RUNGE-KUTTA-DRIFT.] 3 ISOCHRONS Requests calculation and plotting of isochrons. You must specify the interval, in \μsec, after the ISOCHRONS keyword. The appearance of the isochrons is affected by: !Wul_start - the polyline and the polymarker representations "-> graphics -> REPRESENTATION -> item -> ISOCHRON"; - by a series of options which control whether the points on the isochrons are to be joined by lines or simply to be marked, up to which distance isochron points may be joined, whether checks have to be made for intersects between isochrons and drift lines, see "-> &DRIFT -> INTEGRATION-PARAMETERS" for details. !Wul_end Plotting isochrons can be a CPU intensive operation, depending on the number of drift-lines, the number of isochrons and the options that have been chosen. In order to plot only the isochrons and not the drift-lines, one uses ISOCHRONS in conjunction with NO"-> &DRIFT -> DRIFT -> LINE-PLOT". The drift time used for the isochrons is by default measured from the wire or the solid where the electron or ion ends up. This can be changed by using the "-> &DRIFT -> DRIFT -> REVERSE-ISOCHRONS" option. Isochrons are only plotted for electrons and ions that do reach a wire, a solid, a plane or the tube. Isochrons are not plotted for particles that reach a replica of a wire (in case of periodic chambers). Note that isochrons can also be obtained with "-> &DRIFT -> TABLE" CONTOUR and with "-> &DRIFT -> PLOT-FIELD" CONTOUR TIME. These commands do not take the end-point of the electrons into account, and as a result may produce isochrons joining points leading to different wires or solids. [Isochrons are by default not plotted.] 3 REVERSE-ISOCHRONS The time which serves as basis for isochron plotting is, by default, measured from: !Wul_start - "-> &DRIFT -> DRIFT -> TRACK" and "-> &DRIFT -> DRIFT -> EDGES": the surface of the wire, solid, plane or tube on which the drift-line ends; - "-> &DRIFT -> DRIFT -> WIRES": the surface of the wires from where the drift-lines have been computed; - "-> &DRIFT -> DRIFT -> SOLIDS": the surface of the solids from where the drift-lines have been computed. !Wul_end Thus, the drift-lines starting from the track or the edges are by default reversed when isochrons are computed. This behaviour can be changed by using NOREVERSE-ISOCHRONS. If you wish the drift time to be measured from the end point of the drift-line in DRIFT WIRES and DRIFT SOLIDS plot, then you should specify the REVERSE-ISOCHRONS option. [This setting of this option is, like all other DRIFT options, kept from one call to the next.] 3 LINE-PLOT Requests plotting of the drift-lines. You may wish to switch this option off if you want to see only isochrons. Electron drift-lines are plotted with the representation "-> graphics -> REPRESENTATION -> item -> E-DRIFT-LINE" and ion drift-lines with "-> graphics -> REPRESENTATION -> item -> ION-DRIFT-LINE". [This option is initially on.] 3 LINE-PRINT Requests printing of drift-line summary data. This option is not compatible with "-> &DRIFT -> DRIFT -> LINE-PLOT" in interactive VM/CMS (because of system shortcomings) unless the "-> output" has been re-routed (> file). This option is initially off. 3 ELECTRON Requests drifting of electrons. 3 ION Requests drifting of ions. 3 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.] 3 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.] 3 representations The following representations are used in the plots made with the DRIFT command: !Wul_start - the representations used to draw the "-> &FIELD -> AREA" box, - the "-> &DRIFT -> TRACK -> representations" used to draw the track; - "-> graphics -> REPRESENTATION -> item -> COMMENT", text and polyline, to indicate the drift-line status in the "-> &DRIFT -> DRIFT -> TRACK -> graph"s, - "-> graphics -> REPRESENTATION -> item -> E-DRIFT-LINE" to draw the drift-line of an "-> &DRIFT -> DRIFT -> ELECTRON", - "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", polymarker and polyline, to draw the "-> &DRIFT -> DRIFT -> TRACK -> graph"s, - "-> graphics -> REPRESENTATION -> item -> ION-DRIFT-LINE" to draw the drift-line of an "-> &DRIFT -> DRIFT -> ION", - "-> graphics -> REPRESENTATION -> item -> ISOCHRON", polymarker and polyline, to draw isochrons. !Wul_end 2 GET-TRACK Retrieves a prepared track from a dataset written by "-> &DRIFT -> WRITE-TRACK". This saves time since one doesn't have to run "-> &DRIFT -> PREPARE-TRACK" again. Format: !W

  GET-TRACK "-> &DRIFT -> GET-TRACK -> file" ["-> &DRIFT -> GET-TRACK -> member"]
!W
Example: !W
  get-tr lib
!W
(This call will retrieve the first prepared track in the dataset LIB.DAT, which may contain members of different type as well.) 3 file The name of the "-> dataset -> structure -> file" that contains the track description. 3 member The name of the "-> dataset -> structure -> member" that you wish to retrieve. 2 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: !W
  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]
!W
Example: !W
  gra loc-pet 1 4
!W
Chooses rubber band for the second point. 3 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. 4 CHOICE-PET Used for menus. 4 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. 4 PICK-PET Used to select a wire. 4 VALUATOR-PET Used to enter a value. 3 device The device number via which you wish to enter input for a given mode. 4 CHOICE-DEVICE Used for menus. 4 LOCATOR-DEVICE Used to choose a specific point. 4 PICK-DEVICE Used to select a wire. 4 VALUATOR-DEVICE Used to enter a value. 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. 2 GRID Chooses the x (or r) and y (or \φ) density of the grid inside the "-> &DRIFT -> AREA" from which instructions like "-> &DRIFT -> TABLE" will calculate drift-lines. The grid is common to all sections. Format: !W
  GRID  "-> &DRIFT -> GRID -> number"_of_steps_in_x  [number_of_steps_in_y]
!W
Example: !W
  grid 10 20
!W
3 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 \φ) spacing. [Default is 25 for both.] 2 INTEGRATION-PARAMETERS Enables one to change the following: !Wul_start - the Runge Kutta Fehlberg drift-line integration accuracy and maximum step length; - the step size for Monte Carlo drifting; - the range of permitted diffusion scaling factors in Monte Carlo drifting; - the distance from a wire where a electron or ion is considered to be caught by the wire; - the order with which drift-lines are interpolated when using prepared tracks; - the distance at which the integration algorithm for transverse + longitudinal diffusion projects the cloud radially onto the wire; - the method by which the cloud is projected into the wire; - the maximum stack depth and the relative accuracy of the integration of the diffusion coefficient, the Townsend coefficient and the attachment coefficient; - conditions under which isochron segments are joined; - appearance of isochrons. !Wul_end These parameters are used both in this section and in the signal section. Format: !W
  INTEGRATION-PARAMETERS ...
       [INTEGRATION-ACCURACY "-> &DRIFT -> INTEGRATION-PARAMETERS -> accuracy"] ...
       [ NOMAXIMUM-STEP-LENGTH | ...
         MAXIMUM-STEP-LENGTH "-> &DRIFT -> INTEGRATION-PARAMETERS -> maximum_step" ] ...
       [ MONTE-CARLO-TIME-INTERVAL "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" | ...
         MONTE-CARLO-DISTANCE-INTERVAL "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" | ...
         MONTE-CARLO-COLLISIONS "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" ] ...
       [ DIFFUSION-SCALING-RANGE "-> &DRIFT -> INTEGRATION-PARAMETERS -> scale"_min scale_max ] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ATTRACTING-WIRES" | ...
         "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" ] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> REJECT-KINKS" | ...
         NOREJECT-KINKS ] ...
       ["-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS" ntrap] ...
       [INTERPOLATION-ORDER "-> &DRIFT -> INTEGRATION-PARAMETERS -> order"] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> COMPUTE-IF-INTERPOLATION-FAILS" | ...
         ABANDON-IF-INTERPOLATION-FAILS ] ...
       [CLOUD-PROJECTION-DISTANCE "-> &DRIFT -> INTEGRATION-PARAMETERS -> ncloud"] ...
       [CLOUD-PROJECTION-METHOD ...
           { "-> &DRIFT -> INTEGRATION-PARAMETERS -> method -> CENTRAL-VELOCITY-INTEGRATION" | ...
             "-> &DRIFT -> INTEGRATION-PARAMETERS -> method -> INTEGRATION" | ...
             "-> &DRIFT -> INTEGRATION-PARAMETERS -> method -> LONGITUDINAL-DIMENSION" | ...
             "-> &DRIFT -> INTEGRATION-PARAMETERS -> method -> LARGEST-DIMENSION" | ...
             "-> &DRIFT -> INTEGRATION-PARAMETERS -> method -> NO-PROJECTION" } ...
       [DIFFUSION-ACCURACY "-> &DRIFT -> INTEGRATION-PARAMETERS -> \ε"_diff] ...
       [TOWNSEND-ACCURACY \ε_Town] ...
       [ATTACHMENT-ACCURACY \ε_att] ...
       [DIFFUSION-STACK-DEPTH "-> &DRIFT -> INTEGRATION-PARAMETERS -> stack"_diff] ...
       [TOWNSEND-STACK-DEPTH stack_Town] ...
       [ATTACHMENT-STACK-DEPTH stack_att] ...
       ["-> &DRIFT -> INTEGRATION-PARAMETERS -> PROJECTED-PATH-INTEGRATION" | ...
         TRUE-PATH-INTEGRATION ] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> DRAW-ISOCHRONS" | ...
         "-> &DRIFT -> INTEGRATION-PARAMETERS -> MARK-ISOCHRONS" ] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> SORT-ISOCHRONS" | ...
         NOSORT-ISOCHRONS ] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-CONNECTION-THRESHOLD" iso_thr | ...
         NOISOCHRON-CONNECTION-THRESHOLD ] ...
       ["-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-ASPECT-RATIO-SWITCH" iso_aspect] ...
       ["-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-LOOP-THRESHOLD" iso_loop] ...
       [ "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ISOCHRON-CROSSINGS" | ...
         NOCHECK-ISOCHRON-CROSSINGS ]
!W
Example: !W
  int diff-st 5, diff-acc 1.0e-3
!W
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 per mille. 3 accuracy Sets the accuracy of "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" drift-line 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 has no effect on "-> &DRIFT -> methods -> Monte_Carlo" integration and "-> &DRIFT -> methods -> microscopic" tracking. [This parameter is initially set to 10\-8\.] 3 maximum_step The maximum step size that is allowed. The "-> &DRIFT -> methods -> 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. Recommended value: a maximum step length of order 1/10th-1/20th of the distance to be traversed. This parameter has no effect on "-> &DRIFT -> methods -> Monte_Carlo" integration and "-> &DRIFT -> methods -> microscopic" tracking.. [By default, there is no limit to the step size.] 3 step_size The meaning of these parameters depends on the integration technique that is being applied. !Wdl_start !T+ + ----------------------------------------------------------------------------------- Method Description ----------------------------------------------------------------------------------- MC-TIME-INTERVAL Only used for "-> &DRIFT -> methods -> Monte_Carlo" tracking. Steps will have a constant duration in time. Since electrons move much faster than ions, and since the same duration will be used for both, this option is of little practical use in situations where both types of particles are drifting. [Default: 20 psec] MC-DISTANCE-INTERVAL Only used for "-> &DRIFT -> methods -> Monte_Carlo" tracking. An approximately constant spatial length will be used for each step. The steps will as a rule not have exactly the requested length as a result of the diffusion process and to a lesser extent also through non-linearities in the field. This is the most commonly used method since the same settings can be used for both electrons and ions. [Default: 10 \μm] MC-COLLISIONS In "-> &DRIFT -> methods -> Monte_Carlo" tracking, this requests a step length distribution with a mean roughly equal to the specified number of times mean free paths at the local electric and magnetic field. When using "-> &DRIFT -> methods -> microscopic" tracking, the parameter determines how many collisions occur between 2 collisions which are recorded in the drift path. The parameter does not in any way influence tracking. [Default: 100 steps] ----------------------------------------------------------------------------------- !Wdl_end None of these parameters has an effect on "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration. 3 scale When performing "-> &DRIFT -> methods -> Monte_Carlo" drift-line integration, the diffusion tensor is longitudinally stretched at each step to allow for accelerations and transversely stretched to account for convergence of neighbouring drift-lines. Excessively small and large scaling factors are indicative of a locally too large "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size". This is commonly the case in the vicinity of small electrodes such as wires. Garfield therefore reduces the step size locally if the scaling is found to lie outside the range given. The minimum of the scaling range has to be larger than or equal to 0. The maximum has to be larger than 1. Using the default range, one effectively uses the expressions for diffusion spread in the limit of infinitely small steps. This is not appropriate in case the mean free path is substantially larger than a few \μm. [Default: 0.95 as minimum and 1.05 as maximum.] 3 TRAP-RADIUS 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" option) and if the particle passes closer by the wire than a distance of !W
  
  ntrap*radius
!W
then the electron or ion is considered to be caught by the wire. When using "-> &DRIFT -> methods -> microscopic" tracking, it is advisable to set the radius to 1, i.e. not to consider an electron caught until it tries to enter 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.] 3 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.] 3 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: !Wul_start - the point is not located on the prepared track, this can happen if the "-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" or "-> &DRIFT -> TRACK -> HEED -> MULTIPLE-SCATTERING" option is active; - the point is located between 2 tabulated points between which the termination of the drift-line changes; - the point is located in a tabulated section with constant which is shorter than the requested interpolation "-> &DRIFT -> INTEGRATION-PARAMETERS -> order". !Wul_end 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.] 3 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS", 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.] 3 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.] 3 REJECT-KINKS This option requests drift-line calculation to be aborted if the drift-line makes a bend sharper than 90\°. 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. Drift-lines that are terminated because of this condition, are given the "-> &DRIFT -> methods -> status" "Bend sharper than pi/2". 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. This option has effect when drift-line integration is performed using the "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" method, but not when the "-> &DRIFT -> methods -> Monte_Carlo" or "-> &DRIFT -> methods -> microscopic" method is used. [The option is on by default.] 3 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.] 3 method When both transverse and longitudinal diffusion have been entered in the gas section, the diffusion is calculated by propagating a "-> &DRIFT -> methods -> diffusion -> 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: 4 NO-PROJECTION No special treatment when approaching the wire, hence the value of ncloud is not relevant. 4 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. 4 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.] 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). 4 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. 3 \ε A step is subdivided if the difference between the first and second order estimates differ more than a fraction \ε of the total first order estimate without subdivisions. [The default is 10\-3\.] 3 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 2, the maximum is given by MXSTCK, usually set to 5. 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.] 3 PROJECTED-PATH-INTEGRATION "-> &DRIFT -> methods -> Monte_Carlo" drift paths are longer than the mean drift paths computed with the "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" method. Moreover, the path length computed with the Monte Carlo method increases with decreasing step length. As a result, integrating the Townsend and the attachment coefficient over Monte Carlo paths leads to larger multiplications and larger losses than are obtained integrating over Runge Kutta Fehlberg paths. In addition, the integral over Monte Carlo paths is ill-defined since it depends on the step size. To bypass this problem, programs such as Magboltz compute the Townsend coefficient by counting the number of electrons produced in a unit of projected path length measured along the average direction of motion, not in a unit of distance effectively covered by an electron during its random walk motion. When the PROJECTED-PATH-INTEGRATION integration parameter is active, Garfield replicates this approach by integrating the Townsend and attachment coefficients 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. Since electrons occasionally move backwards with respect to the average motion, without this leading to electron losses, the procedure tries to cancel backwards steps against nearby forward steps. A warning message is printed in case of net backwards motion (backscatter). This option has effect on !Wul_start - all Townsend and attachment integrals, such as those shown in the avalanche "-> &DRIFT -> DRIFT -> TRACK -> graph" produced by the DRIFT "-> &DRIFT -> DRIFT -> TRACK" command, those returned by electron drift procedures such as "-> Call -> DRIFT_ELECTRON" and "-> Call -> DRIFT_MC_ELECTRON", and those used for "-> &SIGNAL -> SIGNAL" calculations; - the avalanche statistics computed by "-> Call -> AVALANCHE"; - the avalanche statistics computed by "-> Call -> RND_MULTIPLICATION". !Wul_end [Default is TRUE-PATH-INTEGRATION.] 3 DRAW-ISOCHRONS Requests isochrons to be drawn as lines, rather than marked. When this option is selected, you may also wish to inspect the settings of the other isochron related options. This action of this option can reversed with the "-> &DRIFT -> INTEGRATION-PARAMETERS -> MARK-ISOCHRONS" option. Isochrons are drawn using the "-> graphics -> REPRESENTATION -> item -> ISOCHRON" polyline representation. [By default, isochrons are drawn as lines.] 3 MARK-ISOCHRONS Requests marking the points on the isochrons. If this option is active, no sorting needs to be done. Hence, the other isochron options are ignored. Plotting isochrons is fast with this option switched on. This action of this option can reversed with the "-> &DRIFT -> INTEGRATION-PARAMETERS -> DRAW-ISOCHRONS" option. Isochrons are marked using the "-> graphics -> REPRESENTATION -> item -> ISOCHRON" polymarker representation. [By default, isochrons are drawn as lines.] 3 SORT-ISOCHRONS Depending on the source of the points that serve to draw the isochrons, they can be in some definite order or not. By setting SORT-ISOCHRONS, an attempt is made to order the points in such a manner that the isochrons 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 "travelling 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. Whether an isochron is sorted as a line or as an arc depends on the setting of "-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-ASPECT-RATIO-SWITCH". Whether 2 points on an isochron are connected or not depends on the setting of "-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-CONNECTION-THRESHOLD". The sorting algorithm by itself is fast - the check on intersects between isochrons 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-ISOCHRONS option is ignored when "-> &DRIFT -> INTEGRATION-PARAMETERS -> MARK-ISOCHRONS" is in effect. [By default: sort done] 3 ISOCHRON-CONNECTION-THRESHOLD Points on an isochron 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 (isochrons are only interrupted by drift-line crossings). Selecting NOISOCHRON-CONNECTION-THRESHOLD is tantamount to setting iso_thr to 1. [Initial setting: 0.2] 3 ISOCHRON-ASPECT-RATIO-SWITCH When an isochron appears to be more or less circular, its points are ordered by increasing angle with respect to the centre of gravity. If the isochron, 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 isochron is assumed to be linear, otherwise circular. This switch has effect only when "-> &DRIFT -> INTEGRATION-PARAMETERS -> SORT-ISOCHRONS" has been switched on. [Initial setting: 3] 3 ISOCHRON-LOOP-THRESHOLD Isochrons that appears to be circular (rather than linear, see "-> &DRIFT -> INTEGRATION-PARAMETERS -> ISOCHRON-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 isochron. [Initial setting: 0.2] 3 CHECK-ISOCHRON-CROSSINGS Requests ensuring that drift-lines do not cross isochrons. 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] 2 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 -> DRIFT" command. For DRIFT "-> &DRIFT -> DRIFT -> TRACK", use the "-> &DRIFT -> TRACK" command to set a clustering model. For DRIFT "-> &DRIFT -> DRIFT -> EDGES", DRIFT "-> &DRIFT -> DRIFT -> SOLIDS" and DRIFT "-> &DRIFT -> DRIFT -> WIRES", use the respective LINES option on the DRIFT command line. Format: !W
  LINES lines
!W
Example: !W
  lines 50
!W
2 LORENTZ-ANGLE Prints the Lorentz-angle, i.e. the angle between the drift vector and the electric field, at the point (x,y,z). This command is now superseded by the "-> Call -> LORENTZ_ANGLE" procedure. Format: !W
  LORENTZ-ANGLE x y z
!W
Example: !W
  lorentz 0.5 0.5 1
!W
2 MINIMISE Searches for the minimum of e.g. the drift time over a curve. Format: !W
  MINIMISE "-> &DRIFT -> MINIMISE -> f_min" ...
           [SELECTION-FUNCTION "-> &DRIFT -> MINIMISE -> f_select"] ...
           "-> &DRIFT -> MINIMISE -> ON" f_curve ...
           "-> &DRIFT -> MINIMISE -> RANGE" t_min t_max ...
           ["-> &DRIFT -> MINIMISE -> N" n] ...
           ["-> &DRIFT -> MINIMISE -> ELECTRON" | "-> &DRIFT -> MINIMISE -> ION"] ...
           ["-> &DRIFT -> MINIMISE -> NEGATIVE" | "-> &DRIFT -> MINIMISE -> POSITIVE"] ...
           ["-> &DRIFT -> MINIMISE -> FUNCTION-PRECISION" \ε_f] ...
           ["-> &DRIFT -> MINIMISE -> POSITIONAL-RESOLUTION" \ε_pos] ...
           ["-> &DRIFT -> MINIMISE -> ITERATE-LIMIT" itermax] ...
           ["-> &DRIFT -> MINIMISE -> PRINT" | NOPRINT] ...
           ["-> &DRIFT -> MINIMISE -> DATASET" dataset [member] [REMARK remark]]
!W
Example: !W
  minimise time on '5*"-> algebra -> functions -> cos"(t), 5*"-> algebra -> functions -> sin"(t)' range {pi/4,3*pi/4}
!W
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 one of the "-> introduction -> separators" and since ON expects only one element, "-> introduction -> quotes" are used. RANGE on the other hand expects two elements and quotes should therefore not be used ! 3 f_min The function to be minimised has to depend on at least one of the following variables: !Wtable_start !T+P + + . ------------------------------------------------------------- Symbol Meaning Unit ------------------------------------------------------------- TIME Total drift time \μsec LENGTH Length of the drift-line cm DIFFUSION Integrated diffusion coefficient \μsec AVALANCHE exp(\∫ Townsend dz) probability LOSS exp(-\∫ attachment dz) probability ------------------------------------------------------------- !Wtable_end All variables are of type "-> algebra -> variables -> types -> Number". Further details can be found under the methods used to integrate the "-> &DRIFT -> methods -> diffusion", the "-> &DRIFT -> methods -> multiplication" and the "-> &DRIFT -> methods -> attachment". [The default function to be minimised is TIME.] 3 f_select This function should return a "-> algebra -> variables -> types -> Logical", i.e. either the value True or the value False. If False is returned, then the point will not be considered anymore during the minimisation process. The following variables can be used: !Wtable_start !T+P + + . ------------------------------------------------------------- Symbol Meaning Unit ------------------------------------------------------------- TIME Total drift time \μsec LENGTH Length of the drift-line cm DIFFUSION Integrated diffusion coefficient \μsec AVALANCHE exp(\∫ Townsend dz) probability LOSS exp(-\∫ attachment dz) probability STATUS What happened to the particle see below ------------------------------------------------------------- !Wtable_end All variables are of type "-> algebra -> variables -> types -> Number" except for STATUS which is a "-> algebra -> variables -> types -> 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`, `Hit_X_Replica` and `Hit_X_Solid`. `X` is the label that you have assigned to the wire or solid. Further details can be found under the methods used to integrate the "-> &DRIFT -> methods -> diffusion", the "-> &DRIFT -> methods -> multiplication" and the "-> &DRIFT -> methods -> attachment". [The default selection curve returns always True.] 3 ON ON should be followed be a parametrisation in terms of the variable T of the curve over which the minimisation should take place. The range of T can be specified via RANGE. [No default curve is provided.] 3 RANGE RANGE should be followed by the minimum and the maximum value the variable T is allowed to take during minimisation, see "-> &DRIFT -> MINIMISE -> ON" for further information on T. [No default RANGE is provided.] 3 N The number of points on the curve for the initial scan of the curve. [The default value for N is 20.] 3 ELECTRON Requests that the minimisation be carried out for electrons. [This is the default.] 3 ION Requests that the minimisation be carried out for ions. [By default, minimisation is done for electrons.] 3 POSITIVE Requests that the minimisation be carried out for positively charged electrons or ions. [The default is NEGATIVE.] 3 NEGATIVE Requests that the minimisation be carried out for negatively charged electrons or ions. [This is the default.] 3 FUNCTION-PRECISION The procedure assumes it has converged if the relative change in function value has dropped below \ε_f. [The default value is 10\-4\, which is also the smallest reasonable value on computers like Vax and IBM. On Cray and other computers with 64-bit precision, \ε_f can be made smaller.] 3 POSITIONAL-RESOLUTION The procedure assumes it has converged if the relative change in position of the minimum has dropped below \ε_pos. [The default value is 10\-4\, which is also the smallest reasonable value on computers like Vax and IBM. On Cray and other computers with 64-bit precision, \ε_pos can be made smaller.] 3 ITERATE-LIMIT The maximum number of iteration steps during the minimisation process. [By default 20.] 3 PRINT Requests some printout during the minimisation procedure. [This is default.] 3 DATASET Requests dataset output of the minimisation results. [No such output is produced by default.] 2 OPTIONS Determines whether the drift-lines produced by other commands than the DRIFT instruction are plotted or printed. Commands affected by these options include "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" and "-> &DRIFT -> 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: !W
  OPTIONS ["-> &DRIFT -> OPTIONS -> DRIFT-PRINT" | NODRIFT-PRINT] ...
          ["-> &DRIFT -> OPTIONS -> DRIFT-PLOT" | NO-DRIFT-PLOT] ...
          ["-> &DRIFT -> OPTIONS -> KEY" | NOKEY] ...
          ["-> &DRIFT -> OPTIONS -> CONTOUR-ALL-MEDIA" | "-> &DRIFT -> OPTIONS -> CONTOUR-DRIFT-MEDIUM"] ...
          [NOWIRE-MARKERS | "-> &DRIFT -> OPTIONS -> WIRE-MARKERS"] ...
          [NOCHECK-MAP-INDICES | "-> &DRIFT -> OPTIONS -> CHECK-MAP-INDICES"]
!W
Example: !W
  opt dr-pl nodr-pr
!W
3 DRIFT-PRINT Requests printing of drift-line summary data in a few, nearly forgotten, commands like "-> &DRIFT -> TABLE". Most commands have their local print option. 3 DRIFT-PLOT Requests plotting of the drift-lines used by for instance "-> &DRIFT -> XT-PLOT" and "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION". The option is particularly useful to verify that prepared tracks are interpolated with a reasonable "-> &DRIFT -> INTEGRATION-PARAMETERS -> order", and to judge whether there is a need to set the "-> &DRIFT -> INTEGRATION-PARAMETERS -> COMPUTE-IF-INTERPOLATION-FAILS" option. [The option is by default off.] 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. 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.] 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.] 3 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 "-> &CELL -> OPTIONS -> WIRE-MARKERS" option in the cell section. 3 CHECK-MAP-INDICES Requests a verification of the map index calculation. See the "-> &FIELD -> OPTIONS -> CHECK-MAP-INDICES" option in the field section for further information. 2 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: !W
  PLOT-FIELD ["-> &DRIFT -> PLOT-FIELD -> CONTOUR" ["-> &DRIFT -> PLOT-FIELD -> f"1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                             [N n] ...
                             [LABELS | NOLABELS]] ...
             ["-> &DRIFT -> PLOT-FIELD -> GRAPH" [f2]     [ON f_curve] ...
                             [N n]] ...
                             [SCALE min max] ...
                             [NOPRINT | PRINT] ...
             ["-> &DRIFT -> PLOT-FIELD -> HISTOGRAM" [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                             [BINS nbin]] ...
             ["-> &DRIFT -> PLOT-FIELD -> SURFACE" [f4]   [ANGLES \φ \θ]] ...
             ["-> &DRIFT -> PLOT-FIELD -> VECTOR" [f5 f6 [f7]]] ...
             ["-> &DRIFT -> PLOT-FIELD -> RUNGE-KUTTA-DRIFT" | "-> &DRIFT -> PLOT-FIELD -> MONTE-CARLO-DRIFT"] ...
             ["-> &DRIFT -> PLOT-FIELD -> ELECTRON" | "-> &DRIFT -> PLOT-FIELD -> ION"] ...
             ["-> &DRIFT -> PLOT-FIELD -> POSITIVE" | "-> &DRIFT -> PLOT-FIELD -> NEGATIVE"]
!W
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: !W
  plot hist diffusion vector vdx, vdy surf cont
  plot contour time range 0.1 0.3
!W
(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.) 3 f All functions in the description of the PLOT-FIELD command (f1, f2 ... f6) may depend on the following set of variables: !Wtable_start !T+P + + . ------------------------------------------------------------------------ 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 Survival probability only if data is available STATUS Numeric status code See below P Pressure of the gas - ------------------------------------------------------------------------ !Wtable_end Further details can be found under the methods used to integrate the "-> &DRIFT -> methods -> diffusion", the "-> &DRIFT -> methods -> multiplication" and the "-> &DRIFT -> methods -> attachment". The numeric "-> &DRIFT -> methods -> status" code is a "-> algebra -> variables -> types -> Number", not a string. Other variables can be added on request. 3 CONTOUR Produces a plot of the lines of equal function values. Contours are drawn in the part of the viewing "-> &FIELD -> AREA -> plane" that is located within the current "-> &DRIFT -> AREA" box. The contours are labelled 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 "-> &DRIFT -> DRIFT -> WIRES" ISOCHRONS=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. Contours are plotted starting from their crossings with a regular "-> &DRIFT -> GRID" covering the AREA. Very small contours are not found if the grid is course. It is therefore usually preferable to use a fine grid for contours, even though plotting the contours takes more time. You may also wish to optimise the "-> graphics -> CONTOUR-PARAMETERS", especially if your AREA is very small or highly non-isometric. The contours are drawn with the representation "-> graphics -> REPRESENTATION -> item -> CONTOUR-NORMAL" and are labelled with "-> graphics -> REPRESENTATION -> item -> 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.] 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 "-> &DRIFT -> 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 "-> introduction -> quotes", e.g. !W
  '"-> algebra -> functions -> cos"(pi*t),"-> algebra -> functions -> sin"(pi*t),0'
!W
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. Re-routing 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.] 3 HISTOGRAM The function is sampled over a "-> &DRIFT -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &DRIFT -> 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 "-> Call -> BOOK_HISTOGRAM -> options -> 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.] 3 SURFACE The function is sampled over a "-> &DRIFT -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &DRIFT -> AREA" box. The function values are presented as a three dimensional plot. The plot is first rotated by \φ degrees around the z-axis and then tilted by \θ 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\°. The viewing angles are remembered from one call to the next.] 3 VECTOR This plot shows the flow of a 3-vector sampled over a "-> &DRIFT -> GRID" grid of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &DRIFT -> AREA" box. The vectors are projected onto the current viewing plane. The z-component is set to 0, if not explicitly 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" representation. The appearance of the arrow is influence by the "-> graphics -> ARROW-TIP-ANGLE" and "-> graphics -> ARROW-TIP-LENGTH" settings. [The default functions are VDX, VDY, VDZ, i.e. the drift velocity.] 3 ELECTRON Requests drifting of electrons, not ions. [This is default.] 3 ION Requests drifting of ions, not electrons. [This is not default.] 3 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. 3 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. 3 RUNGE-KUTTA-DRIFT Requests the use of the "-> &DRIFT -> methods -> 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 controlling the accuracy are adjusted for chambers that are several centimetres large. When studying much smaller structures, at the \μm scale, one may wish to request more "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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.] 3 MONTE-CARLO-DRIFT Requests "-> &DRIFT -> methods -> Monte_Carlo" calculation of a drift path, instead of a "-> &DRIFT -> methods -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" as set with the "-> &DRIFT -> INTEGRATION-PARAMETERS" command. [The initial default is RUNGE-KUTTA-DRIFT.] 2 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: !Wul_start - the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" command uses prepared tracks, but performs the preparation itself; - prepared tracks are used in signal simulations, provided the "-> &SIGNAL -> SIGNAL -> INTERPOLATE-TRACK" option has been switched on, and provided the user has performed a track preparation; - in user procedures that call "-> Call -> INTERPOLATE_TRACK". !Wul_end The track thus prepared, can be saved in a dataset with "-> &DRIFT -> WRITE-TRACK" from where it can be retrieved in subsequent runs with "-> &DRIFT -> GET-TRACK". Format: !W
  PREPARE-TRACK ...
       ["-> &DRIFT -> PREPARE-TRACK -> ATTACHMENT-COEFFICIENT" | NOATTACHMENT-COEFFICIENT] ...
       ["-> &DRIFT -> PREPARE-TRACK -> DIFFUSION-COEFFICIENT" | NODIFFUSION-COEFFICIENT] ...
       ["-> &DRIFT -> PREPARE-TRACK -> TOWNSEND-COEFFICIENT" | NOTOWNSEND-COEFFICIENT] ...
       ["-> &DRIFT -> PREPARE-TRACK -> LINES" n]
!W
Example: !W
  prep-tr
!W
(Accept all defaults, usually adequate.) 3 ATTACHMENT-COEFFICIENT The attachment coefficient will be integrated and the result will be stored along with the other data if this option is selected. 3 DIFFUSION-COEFFICIENT The diffusion coefficient will be integrated and the result will be stored along with the other data if this option is selected. 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. 3 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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 "-> &DRIFT -> LINES".] 2 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 "-> &DRIFT -> DRIFT -> WIRES", "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" and "-> &DRIFT -> XT-PLOT". Format: See "-> &FIELD -> SELECT" Example: !W
  sel (1 s) 2 f
!W
(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.) 2 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 "-> Call -> DRIFT_ELECTRON", "-> Call -> DRIFT_ELECTRON_3", "-> Call -> DRIFT_MC_ELECTRON", "-> Call -> DRIFT_POSITRON", "-> Call -> DRIFT_POSITRON_3", "-> Call -> DRIFT_MC_POSITRON", "-> Call -> DRIFT_ION", "-> Call -> DRIFT_ION_3", "-> Call -> DRIFT_MC_ION", "-> Call -> DRIFT_MC_NEGATIVE_ION", "-> Call -> DRIFT_NEGATIVE_ION" or "-> Call -> DRIFT_NEGATIVE_ION_3" procedure, then retrieving it with "-> Call -> GET_DRIFT_LINE" and finally making the graph with "-> Call -> PLOT_GRAPH". Format: !W
  SINGLE  FROM  x y ...
          ["-> &DRIFT -> SINGLE -> PLOT" "-> &DRIFT -> SINGLE -> f"1 VS f2 | NOPLOT] ...
          ["-> &DRIFT -> SINGLE -> PRINT" f3 | NOPRINT] ...
          ["-> &DRIFT -> SINGLE -> NEGATIVE" | "-> &DRIFT -> SINGLE -> POSITIVE"] ...
          ["-> &DRIFT -> SINGLE -> ELECTRON" | "-> &DRIFT -> SINGLE -> ION"]
!W
Examples: !W
  single from 0.5 0.3 plot diffusion vs path
  single from 0.1 0.2 print vdx
!W
3 f The functions may use the following variables: !Wtable_start !T+P + + . ------------------------------------------------------------------------ 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 ------------------------------------------------------------------------ !Wtable_end The numeric "-> &DRIFT -> methods -> status" code is a number which tells where the particle ended. These codes have a 1-1 correspondence with the status strings which are displayed in regular program output. [No meaningful default functions are provided.] 3 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.] 3 PLOT Requests a graph of function f1, plotted along the y-axis, vs function f2, plotted along the x-axis. [By default, a graph is not made.] 3 ELECTRON The drift-line will be calculated for an electron. 3 ION The drift-line will be calculated for an ion. 3 POSITIVE The particle which is drifted has a positive charge. 3 NEGATIVE The particle which is drifted has a negative charge. 2 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 "-> Call -> ELECTRON_VELOCITY" and "-> Call -> ION_VELOCITY" procedures. Format: !W
  SPEED x y z   [ELECTRON | ION]   [NEGATIVE | POSITIVE]
!W
Example: !W
  speed 0.5 1.5 0
!W
2 TABLE Prints a table of drift times for electrons or ions starting from a "-> &DRIFT -> GRID" of regularly spaced points inside the "-> &DRIFT -> AREA". The POSITIVE or NEGATIVE keyword should, if used, be at the end of the command. Format: !W
  TABLE ["-> &DRIFT -> TABLE -> TABLE" | NOTABLE] ...
        [NOCONTOUR | "-> &DRIFT -> TABLE -> CONTOUR"] ...
        [ELECTRON | ION] ...
        [NEGATIVE | POSITIVE]
!W
This command must be entered on a single line ! Example: !W
  table
!W
(Only produce the table, no contours.) 3 TABLE Requests printed output from the TABLE instruction. It is probably advisable to re-rout it to some output file. 3 CONTOUR Requests that the results from this instruction be represented as a set of equal drift time contours. This plot is necessarily much more crude than the one obtained with DRIFT WIRES NOLINE-PLOT ISOCHRONS=deltat. 2 TIME Times n drift-line calculations [default: 10]. Format: !W
  TIME [n]
!W
Example: !W
  time 5
!W
2 TIMING Computes the arrival time distribution of the n'th electron over a given area. Unlike the "-> &DRIFT -> 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 "-> &DRIFT -> TRACK" statement. Format: !W
  TIMING [ELECTRONS {"-> &DRIFT -> TIMING -> electron" | LAST | ONE-BUT-LAST | ... }] ...
         ["-> &DRIFT -> TIMING -> TIME-WINDOW" tmin tmax ] ...
         ["-> &DRIFT -> TIMING -> X-RANGE" xmin xmax]
         ["-> &DRIFT -> TIMING -> Y-RANGE" ymin ymax] ...
         ["-> &DRIFT -> TIMING -> ANGLE-RANGE" phimin phimax] ...
         [BINS "-> &DRIFT -> TIMING -> bins"] ...
         [ITERATIONS "-> &DRIFT -> TIMING -> loops"] ...
         [RUNGE-KUTTA-DRIFT | MONTE-CARLO-DRIFT] ...
         [NOATTACHMENT | "-> &DRIFT -> TIMING -> ATTACHMENT"] ...
         ["-> &DRIFT -> TIMING -> WEIGHTING-FUNCTION" weight] ...
         [NOKEEP-HISTOGRAMS | "-> &DRIFT -> TIMING -> KEEP-HISTOGRAMS"] ...
         [NOPLOT-OVERALL | PLOT-OVERALL] ...
         [NOPLOT-SELECTED-ELECTRON | PLOT-SELECTED-ELECTRON] ...
         [NOPRINT-OVERALL | PRINT-OVERALL] ...
         [NOPRINT-SELECTED-ELECTRON | PRINT-SELECTED-ELECTRON]
!W
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 "-> OPTIONS -> PROGRESS-PRINT" global option enables you to follow the progress of the computations. Example: !W
  "-> &DRIFT -> track" muon energy 20 GeV
  timing electron 3 last y-range -0.3 +0.3
!W
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 "-> &DRIFT -> AREA". 3 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.] 3 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. 3 X-RANGE The part of the "-> &DRIFT -> AREA" to be covered by the tracks. Tracks are generated uniformly over this x-range. The "-> &DRIFT -> TIMING -> WEIGHTING-FUNCTION" can be used to assign probabilities to the various x values. [Default: the entire x-range of the AREA.] 3 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 "-> &DRIFT -> LINES" parameter does not compensate. [Default: the entire y-range of the AREA.] 3 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 "-> &DRIFT -> TIMING -> 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.] 3 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 "-> &DRIFT -> INTEGRATION-PARAMETERS". [Default: Runge-Kutta-Fehlberg integration is used.] 3 ATTACHMENT Requests that attachment data is taken into account. [Default: attachment data is not taken into account.] 3 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 "-> &DRIFT -> TIMING -> X-RANGE" and the "-> &DRIFT -> TIMING -> ANGLE-RANGE". [Default: a weight of 1 is assigned to each track.] 3 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.] 3 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 !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. [Default: histograms are not kept.] 3 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.] 3 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. 3 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. 2 TRACK In Garfield, the track is a line in space and a model for generating clusters over this line. The track is widely used, for instance by the "-> &FIELD -> PLOT-FIELD" command in the field section, the "-> &OPTIMISE -> SET" command in the optimisation section, the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION", "-> &DRIFT -> DRIFT", "-> &DRIFT -> PLOT-FIELD" and "-> &DRIFT -> TIMING" commands in the drift section as well as by the "-> &SIGNAL -> PLOT-FIELD" and "-> &SIGNAL -> SIGNAL" commands in the signal section. All sections use the same track. The track definition command has an elaborate format that stems from its broad use. For field plotting and potential optimisation, it is sufficient to enter the track location - for most other applications you should specify a clustering model too: !Wul_start * Location of the track: One can indicate the location of the track in 3 manners: !Wul_start - Tracks in Garfield are line segments, normally identified by a begin and an end point. This is adequate for drawing graphs, and for high energy particles. - Low energy particles undergo multiple scattering and may also be stopped in the gas. It is therefore more appropriate to describe these by a starting point and an initial direction. You may also give a begin and end point pair, which will be used to compute an initial direction. - One may also, for some applications, request a point-track, i.e. a track of which start and end point coincide. This can sometimes be used as a poor approximation of a photon. !Wul_end * Clustering model: Garfield recognises 9 models to distribute clusters or points over the track: !Wul_start - "-> &DRIFT -> TRACK -> FIXED-NUMBER": deposition of an electron or ion at regularly spaced intervals. This model is mainly used for making graphs, it has no physical meaning. - "-> &DRIFT -> TRACK -> EQUAL-SPACING": deposition of the mean number of clusters as specified in the gas section, at regularly spaced points along the track. This model has no physical meaning, but can be used to estimate the impact of cluster interval fluctuations. - "-> &DRIFT -> TRACK -> EXPONENTIAL-SPACING": deposition of clusters of electrons at random locations along the track, respecting the information from the gas section. This model can be accurate, given good quality gas data. - "-> &DRIFT -> TRACK -> WEIGHTED-DISTRIBUTION": deposition of electrons or ions over the track such that the positions are distributed according to a user specified function. This model is used to study the impact of background electron or ion sources. - "-> &DRIFT -> TRACK -> SINGLE-CLUSTER": a single cluster of electrons is generated per track at a random location along it. This model could be used as a rough approximation of a photon. - "-> &DRIFT -> TRACK -> HEED": a simulation of the interactions between the particle and the gas using the Heed program. - "-> &DRIFT -> TRACK -> SRIM": a simulation of the interactions between the particle and the gas based on an energy loss table produced by the SRIM program. - "-> &DRIFT -> TRACK -> TRIM": a simulation of the interactions between the particle and the gas based on an energy loss table produced by the TRIM program. - "-> &DRIFT -> TRACK -> EQUAL-FLUX-INTERVALS": generation of a user determined number of points at equal flux intervals. This model can be used to represent the electric field strength by the spacing of drift-lines. - "-> &DRIFT -> TRACK -> CONSTANT-FLUX-INTERVALS": generation of points spaced by a user determined flux interval. This model is used as a crude means to determine the transparency of elements. - further models can be added on request. !Wul_end !Wul_end 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 \δ-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. You may, in a single TRACK statement, set parameters for several models. To avoid ambiguity it is then advisable to type one of the model names (FIXED-NUMBER, EQUAL-SPACING etc) at the end of the line. Format: !W
  TRACK  [ x0 y0 | x0 y0 x1 y1 | ...
           x0 y0 z0 | x0 y0 z0 x1 y1 z1 | ...
           "-> &DRIFT -> TRACK -> FROM" x0 y0 [z0] | ...
           { "-> &DRIFT -> TRACK -> TO" x1 y1 [z1] | "-> &DRIFT -> TRACK -> DIRECTION" dx dy [dz] "-> &DRIFT -> TRACK -> RANGE" range } ] ...
         [ "-> &DRIFT -> TRACK -> FIXED-NUMBER" ]  ...
              [ "-> &DRIFT -> TRACK -> FIXED-NUMBER -> LINES" nline ]                    | ...
         [ "-> &DRIFT -> TRACK -> EQUAL-SPACING" ]                       | ...
         [ "-> &DRIFT -> TRACK -> EXPONENTIAL-SPACING" ]                 | ...
         [ "-> &DRIFT -> TRACK -> SINGLE-CLUSTER" ]                      | ...
         [ "-> &DRIFT -> TRACK -> WEIGHTED-DISTRIBUTION" ] ...
              [ "-> &DRIFT -> TRACK -> WEIGHTED-DISTRIBUTION -> WEIGHTING-FUNCTION" { f | weight vs coordinate } ] ...
              [ "-> &DRIFT -> TRACK -> WEIGHTED-DISTRIBUTION -> SAMPLES" nsample ]                | ...
         [ "-> &DRIFT -> TRACK -> HEED" ] ...
              [ "-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" | NODELTA-ELECTRONS ] ...
              [ "-> &DRIFT -> TRACK -> HEED -> TRACE-DELTA-ELECTRONS" | NOTRACE-DELTA-ELECTRONS ] ...
              [ NO"-> &DRIFT -> TRACK -> HEED -> MULTIPLE-SCATTERING" | MULTIPLE-SCATTERING ] ...
              [ NO"-> &DRIFT -> TRACK -> HEED -> ENERGY-CUT" | ENERGY-CUT ] ...
              [ "-> &DRIFT -> TRACK -> HEED -> SWITCH-ELECTRON-TO-CHARGED" eswitch ] ...
              [ "-> &DRIFT -> TRACK -> HEED -> particle" | "-> &DRIFT -> TRACK -> HEED -> MASS" mass "-> &DRIFT -> TRACK -> HEED -> CHARGE" charge ] ...
              [ "-> &DRIFT -> TRACK -> HEED -> ENERGY" energy ]                  | ...
         [ "-> &DRIFT -> TRACK -> SRIM" ] ...
              "-> &DRIFT -> TRACK -> SRIM -> ENERGY" energy ...
              [ "-> &DRIFT -> TRACK -> SRIM -> particle" | "-> &DRIFT -> TRACK -> SRIM -> MASS" mass "-> &DRIFT -> TRACK -> SRIM -> CHARGE" charge ] ...
              [ "-> &DRIFT -> TRACK -> SRIM -> FLUCTUATION-MODEL" model ] ...
              [ "-> &DRIFT -> TRACK -> SRIM -> LATERAL-STRAGGLING" | NOLATERAL-STRAGGLING] ...
              [ "-> &DRIFT -> TRACK -> SRIM -> LONGITUDINAL-STRAGGLING" | NOLONGITUDINAL-STRAGGLING] ...
              [ "-> &DRIFT -> TRACK -> SRIM -> FAST-VAVILOV" | PRECISE-VAVILOV] ...
              [ "-> &DRIFT -> TRACK -> SRIM -> GROUPING" [AUTOMATIC | NONE | n_e ]]     | ...
         [ "-> &DRIFT -> TRACK -> TRIM" ] ...
         [ "-> &DRIFT -> TRACK -> EQUAL-FLUX-INTERVALS" ] ...
              [ "-> &DRIFT -> TRACK -> EQUAL-FLUX-INTERVALS -> FLUX-LINES" n]                    | ...
         [ "-> &DRIFT -> TRACK -> CONSTANT-FLUX-INTERVALS" ] ...
              [ "-> &DRIFT -> TRACK -> CONSTANT-FLUX-INTERVALS -> FLUX-INTERVAL" dv]
!W
Examples: !W
  track * * * 5
!W
Keep all old values except the y coordinate of the end point. !W
  track 1 1 1 2 2 2 
!W
Defines a track from (1,1,1) to (2,2,2). !W
  track from 1 1 1 direction 0 0 1 range 5
  track mu+ energy 10 GeV lines 10 multiple-scattering nodelta
  track fixed
  "-> &DRIFT -> drift" track
  track heed
  drift track
!W
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 \δ-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. 3 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.] 3 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.] 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.] 3 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.] 3 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 "-> &GAS -> 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. 4 LINES Number of electrons or ions deposited on the track. Used only with the "-> &DRIFT -> TRACK -> 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] 3 EQUAL-SPACING Requests a clustering model in which the distance between adjacent clusters is constant, and equal to !W
  1 / mean
!W
where "mean" is the mean number of clusters per cm as entered with the "-> &GAS -> PARAMETERS -> MEAN" option of the "-> &GAS -> PARAMETERS" statement in the gas section. The cluster size distribution will usually be taken from a "-> &GAS -> CLUSTER" statement, but can also be derived from data entered with "-> &GAS -> 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. 3 EXPONENTIAL-SPACING Requests a model in which the number of clusters generated along a straight track is Poisson distributed with a mean of: !W
  mean * length
!W
where "mean" is the mean number of clusters per cm as entered with the "-> &GAS -> PARAMETERS -> MEAN" option of the "-> &GAS -> 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 "-> &GAS -> CLUSTER" statement, but can also be derived from data entered with "-> &GAS -> 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. 3 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. 4 WEIGHTING-FUNCTION The distribution of the points along the track can be specified in either of 2 ways: !Wul_start - As a function in terms of the variable T that runs from 0 at the starting point of the track to 1 at the end point of the track. - As a set of 2 matrices separated by the word 'VS', the first matrix is the weight and the second should be a vector of coordinates defined like T, i.e. running from 0 to 1 for begin and end point of the track. !Wul_end The function should return only non-negative values with a total contents larger than zero. The function need not be normalised. 4 SAMPLES The number of sampling points in the WEIGHTED-DISTRIBUTION model. 3 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 "-> &GAS -> CLUSTER" or the "-> &GAS -> PARAMETERS" statement. This model differs from "-> &DRIFT -> TRACK -> 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 \55\Fe source, provided an adequate cluster size distribution is entered. If this keyword is used, it should be the last keyword on the command line. 3 HEED This option requests 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 \δ-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 "-> &GAS -> 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 "-> &GAS -> PARAMETERS" and "-> &GAS -> CLUSTER" statements is not used when clustering is performed hy Heed. Since Heed will occasionally generate \δ-electrons, which are not located on the track, it is advisable to switch on the "-> &DRIFT -> INTEGRATION-PARAMETERS -> COMPUTE-IF-INTERPOLATION-FAILS" integration parameter if you intend to use commands that perform track preparation. 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 kinetic energy and by the options related to multiple scattering and \δ-electrons. Reference: I.B.\ Smirnov, NIM\ A\ 554 (2005) 474. 4 particle Some common particles can be identified by name: !Wtable_start !T+SP + R R . ------------------------------------------------------------ Name Particle Mass [MeV] Charge ------------------------------------------------------------ ELECTRON e\-\ 0.51099907 -1 POSITRON e\+\ 0.51099907 +1 MU-MINUS \μ\-\ 105.658389 -1 MU-PLUS \μ\+\ 105.658389 +1 TAU-MINUS \τ\-\ 1777.00 -1 TAU-PLUS \τ\+\ 1777.00 +1 GAMMA photon 0 0 PION-MINUS \π\-\ 139.56995 -1 PION-0 \π\0\ 134.9764 0 PION-PLUS \π\+\ 139.56995 +1 KAON-MINUS K\-\ 493.677 -1 KAON-0 neutral K or anti-K 497.672 0 KAON-PLUS K\+\ 493.677 +1 PROTON proton (p) 938.27231 +1 ANTI-PROTON anti-proton (p-bar) 938.27231 -1 NEUTRON neutron (n) 939.56563 0 ANTI-NEUTRON anti-neutron (n-bar) 939.56563 0 ------------------------------------------------------------ !Wtable_end 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. 5 ELECTRON Electrons are treated as \δ-electrons and should have energies in the order of a few keV. \δ-Electrons with an energy less than twice the cuteneBdel compilation parameter of Heed, usually set to 1\ keV, do not undergo scattering during their absorption into ionisation electrons. When using electrons as primary particle, it is advisable not to use the "-> &DRIFT -> TRACK -> HEED -> ENERGY-CUT" option. Mass: 0.51099907\ MeV, charge: -1 5 POSITRON Positrons are treated as \δ-electrons and should have energies in the order of a few keV. Mass: 0.51099907\ MeV, charge: +1 5 MU-MINUS Treated as an ordinary charged particle. Mass: 105.658389\ MeV, charge: -1 5 MU-PLUS Treated as an ordinary charged particle. Mass: 105.658389\ MeV, charge: +1 5 TAU-MINUS Treated as an ordinary charged particle. Mass: 1777.00\ MeV, charge: -1 5 TAU-PLUS Treated as an ordinary charged particle. Mass: 1777.00\ MeV, charge: +1 5 GAMMA Treated as a photo electron, hence only absorbed through the photo-electric effect. The energies should not far exceed 10\ keV. Mass: 0, charge: 0. Example: !W
  "-> &CELL"
  "-> &CELL -> plane" x=-10
  plane x=+10 v=2000

  "-> &GAS"
  arg-50-eth-50
  "-> &GAS -> heed" argon 70 co2 30

  "-> &DRIFT"
  "-> &DRIFT -> area" -10 -10 -9 10 
  track -10 5 10 5 gamma energy 5.9 kev
  "-> Global" done
  Call "-> Call -> book_histogram"(xhist,100,-10,-5)
  Call "-> Call -> book_histogram"(nhist,100,50,250)
  For i From 1 To 1000 Do
     If "-> algebra -> functions -> entier"(i/100)*100=i Then Say "Iteration {i} ..."
     Call "-> Call -> new_track"
     Global nelec=0
     Do
        Call "-> Call -> get_cluster"(x,y,z,e,n,done)
        If done Then "-> Do -> Leave"
        Call "-> Call -> fill_histogram"(xhist,x)
        Global nelec=nelec+1
     Enddo
     Call "-> Call -> fill_histogram"(nhist,nelec)
  Enddo
  Call "-> Call -> plot_histogram"(nhist)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_histogram"(xhist)
  Call "-> Call -> plot_end"
!W
Simulation of the absorption of an \55\Fe photon. 5 PION-MINUS Treated as an ordinary charged particle. Mass: 139.56995\ MeV, charge: -1 5 PION-0 Not meaningful. 5 PION-PLUS Treated as an ordinary charged particle. Mass: 139.56995\ MeV, charge: +1 5 KAON-MINUS Treated as an ordinary charged particle. Mass: 493.677\ MeV, charge: -1 5 KAON-0 Not meaningful: Heed does not generate ionisation deposits for uncharged particles with the exception of photons. 5 KAON-PLUS Treated as an ordinary charged particle. Mass: 493.677\ MeV, charge: +1 5 PROTON Treated as an ordinary charged particle. Mass: 938.27231\ MeV, charge: +1 5 ANTI-PROTON Treated as an ordinary charged particle. Mass: 938.27231\ MeV, charge: -1 5 NEUTRON Not meaningful: Heed does not generate ionisation deposits for uncharged particles with the exception of photons. 5 ANTI-NEUTRON Not meaningful: Heed does not generate ionisation deposits for uncharged particles with the exception of photons. 4 MASS If the "-> &DRIFT -> TRACK -> HEED -> 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] 4 CHARGE If the "-> &DRIFT -> TRACK -> HEED -> 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 by Heed, but for SRIM purposes, all non-zero charges are permitted. 4 ENERGY The kinetic energy of the particle traversing the chamber. The Heed program is designed for GeV-energy charged particles, not for low energy particles which stop in the gas. For these, the "-> &DRIFT -> TRACK -> SRIM" program might be more suitable. The kinetic energy Ekin is related to the energy E by the relation E\ =\ Ekin\ +\ m, where m is the mass of the particle. In high energy physics, it is usual to quote the energy E of a particle, not the kinetic energy. The kinetic 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). For reasons of numerical stability, Heed requires the kinetic energy of the particle to be larger than 10\-3\ times the particle mass. [Default: 1 GeV] 4 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 off by default.] 4 DELTA-ELECTRONS Heed generates its electrons through \δ-electrons. If you are not interested in the spatial extent of \δ-electrons, you may opt to have all electrons moved to the location of the interaction that created the \δ-electron. The DELTA-ELECTRONS option is compatible with track preparation, e.g. in the context of signal calculations, 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 \δ-electrons off. [\δ-Electrons are by default kept as they come out of Heed.] 4 TRACE-DELTA-ELECTRONS \δ-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. \δ-Electrons are not traced either when the NO"-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" option is specified. [Tracing is on by default.] 4 ENERGY-CUT Heed assumes that the energy of the primary particle far exceeds typical ionisation losses. A fortiori, it assumes that the primary particle will traverse the detector volume. The interface will, on demand by setting the ENERGY-CUT option, remove ionisation electrons after the primary particle has lost all its energy. Bear in mind that simulations are inherently inaccurate if this option has an effect. This option will occasionally lead to the loss of an ionisation electron when the primary particle is an "-> &DRIFT -> TRACK -> HEED -> particle -> ELECTRON". [This option is off by default.] 4 SWITCH-ELECTRON-TO-CHARGED Heed simulates primary "-> &DRIFT -> TRACK -> HEED -> particle -> ELECTRON"s as \δ-electrons, using a model that is not appropriate for energies beyond approximately 100 keV. Electrons with a larger energy are better processed as generic charged particles. This option sets the energy at which this switch-over takes place. The energy is to be specified in MeV. [Default: 0.1 MeV = 100 keV.] 3 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 "-> &FIELD -> AREA -> 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. 4 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] 3 SRIM Generates electron clusters along a track, trying to be compatible with the energy loss, range and straggling tables computed by the SRIM program. Such tables must have been read on beforehand, in the gas section, using the "-> &GAS -> SRIM" command. Also the "-> &GAS -> PARAMETERS -> A" and "-> &GAS -> PARAMETERS -> Z" parameters of the gas must have been set in the gas section. When using this clustering model, you have to specify the kinetic "-> &DRIFT -> TRACK -> SRIM -> energy". You may also specify the "-> &DRIFT -> TRACK -> SRIM -> mass", and "-> &DRIFT -> TRACK -> SRIM -> charge", of the particle that traverses the chamber, even though this data is contained in, and extracted from, the SRIM tables. The SRIM tables contain in addition the following data: !Wul_start - a lost of energies at which losses and straggling have been computed; - average energy lost per unit distance via electromagnetic processes, for each energy; - average energy lost per unit distance via nuclear processes, for each energy; - projected path length, for each energy; - longitudinal straggling, for each energy; - transverse straggling, for each energy. !Wul_end Note that these tables contain only average quantities, not their distributions. The interface tries to generate individual tracks which statistically reproduce the above quantities. It does this by starting with a particle with the given "-> &DRIFT -> TRACK -> SRIM -> energy" and a direction derived from the beginning and ending point of the track. Then, iteratively, !Wul_start - the electromagnetic and nuclear energy loss per unit length are interpolated at the current particle energy; - a step is made with a length over which the particle will produce on average a certain number of electrons (see "-> &DRIFT -> TRACK -> SRIM -> GROUPING"), the length is computed by dividing the electromagnetic energy loss by the "-> &GAS -> SRIM -> work" function of the medium; - the longitudinal and transverse scatter are interpolated for the current particle energy; - the scatter is scaled to the length of the step to be taken; - the position is updated for step length and scatter; - although in principle also the direction of the particle changes as a result of scattering, no change in direction is applied since this tends to lead to much overestimated overall straggling; - a randomised actual electromagnetic energy loss over the step is computed using as mean the electromagnetic energy loss interpolated earlier, plus a Monte-Carlo generated fluctuation according to the selected "-> &DRIFT -> TRACK -> SRIM -> fluctuation-model"; - the particle energy is diminished by the actual electromagnetic and average nuclear energy over the step. !Wul_end Iteration ends when either the maximum length of the track has been reached, or when the particle has no energy left. Example: displaying the Bragg curve !W
  "-> &DRIFT"
  "-> &DRIFT -> area" -1 -10 30 10
  "-> &DRIFT -> track" 0 0 20 0 ...
      "-> &DRIFT -> TRACK -> SRIM -> energy" 10 MeV ...
      "-> &DRIFT -> TRACK -> SRIM -> charge" 2 ...
      "-> &DRIFT -> TRACK -> SRIM -> grouping"=auto ...
      "-> &DRIFT -> TRACK -> SRIM -> fluctuation-model"=gaussian

  Call "-> Call -> book_histogram"(hx,100,0,8)
  For i From 1 To 100 "-> Do"
     Call "-> Call -> new_track"
     Do
        Call "-> Call -> get_cluster"(x,y,z,n,e,done)
        If done Then "-> Do -> Leave"
        Call "-> Call -> fill_histogram"(hx,x,n)
     Enddo
  Enddo
  Call "-> Call -> plot_histogram"(hx,`x [cm]`,`Deposits vs x`)
  Call "-> Call -> plot_end"
!W
The histogram hx is booked for a range of [0\ cm, 8\ cm] - we can't use an automatic range here since the range will be determined from the first few entries and the x-coordinates will come in sequence. 4 LATERAL-STRAGGLING Requests lateral straggling be applied at each step of the SRIM track generation. [By default, switched on.] 4 LONGITUDINAL-STRAGGLING Requests longitudinal straggling be applied at each step of the SRIM track generation. Slight range variations may remain as a result of path length variations if lateral straggling is in effect. Since longitudinal straggling is SRIMs way to introduce energy loss fluctuations, this option should be switched off when energy loss fluctuations are introduced by other means. See for this the "-> &DRIFT -> TRACK -> SRIM -> FLUCTUATION-MODEL" options. [By default, switched on.] 4 FAST-VAVILOV Requests the use of the fast Vavilov random number generator, which is equivalent to the "-> Call -> RND_VAVILOV_FAST". The alternative is the use of the precise Vavilov generator, which internally is the same as "-> Call -> RND_VAVILOV". In most cases, the additional precision afforded by using the precise generator is not justified by the overall precision of the energy loss generator. [Default is the fast generator.] 4 GROUPING SRIM is aimed at low energy nuclear particles which deposit large numbers of electrons in a gas. It would neither be practical nor useful in most cases to treat each of these electrons individually. Garfield therefore by default groups the electrons such that, in all, one will have of order MXCLUS/2 clusters. You may override this by manually specifying a grouping size. [Automatic grouping is default.] 4 ENERGY The kinetic energy of the particle traversing the chamber. The kinetic energy Ekin is related to the energy E by the relation E\ =\ Ekin\ +\ m, where m is the mass of the particle. In high energy physics, it is usual to quote the energy E of a particle, not the kinetic energy. The kinetic 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). [No default; mandatory parameter] 4 MASS Refer to the Heed "-> &DRIFT -> TRACK -> HEED -> MASS" specification. [By default, the mass found in the SRIM table.] 4 CHARGE Refer to the Heed "-> &DRIFT -> TRACK -> HEED -> CHARGE" specification. [By default, the charge found in the SRIM table.] 4 particle Refer to the Heed "-> &DRIFT -> TRACK -> HEED -> particle" specification. 4 FLUCTUATION-MODEL Depending on the energy of the particle traversing the gas, various energy loss fluctuation models may be applicable. The SRIM output does not specify the model to use. By default, Garfield uses a combined model which is described in http://cern.ch/rjd/Garfield/vavilov.ps This model uses the Landau distribution for small steps, the Vavilov distribution for medium steps and the Gaussian distribution for long steps. The parameters of these distributions are automatically updated according to the particle properties ("-> &DRIFT -> TRACK -> SRIM -> mass", "-> &DRIFT -> TRACK -> SRIM -> charge" and kinetic "-> &DRIFT -> TRACK -> SRIM -> energy") and the gas properties ("-> &GAS -> PARAMETERS -> A", "-> &GAS -> PARAMETERS -> Z" and the density "-> &GAS -> PARAMETERS -> rho"). The following models are available: !Wul_start - NO-FLUCTUATIONS: no fluctuations, equivalent to setting the fluctuation scale to 0; - LANDAU: an (untruncated) Landau distribution; - VAVILOV: a Vavilov distribution, provided the kinematic parameters are within the range of applicability, otherwise the fluctuations are set to 0; - GAUSSIAN: normal distribution; - COMBINED: a combination of the Landau, Vavilov and Gaussian models, each applied in their alleged domain of applicability. !Wul_end Whenever using a Vavilov distribution, whether by using the "combined" model or by requesting the Vavilov distribution explicitly, you have the choice between two generators, a fast one ("-> &DRIFT -> TRACK -> SRIM -> FAST-VAVILOV") and a more precise one (PRECISE-VAVILOV). When explicitly requesting the use of the Vavilov distribution, beware of the limitations in applicability which are explained in the note cited above. The permissible parameter range is that of the "-> Call -> RND_VAVILOV" or "-> Call -> RND_VAVILOV_FAST" procedure, depending on the choice of generator. Please note that range fluctuations should be switched off with the NO"-> &DRIFT -> TRACK -> SRIM -> LONGITUDINAL-STRAGGLING" option if energy loss fluctuations are introduced. [Default: the combined model.] 3 TRIM Generates clusters according to a file generated by the TRIM program and read using the "-> &GAS -> TRIM" command in the "-> &GAS" section. Interface written by James Butterworth. 3 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 "-> &FIELD -> AREA -> 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. 4 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.] 3 representations The track is plotted using the following representations: !Wul_start - the track location is drawn with "-> graphics -> REPRESENTATION -> item -> TRACK", a point track uses the polymarker representation, a line track the polyline representation; - when using the Heed model, the \δ- and Auger-electrons are shown with "-> graphics -> REPRESENTATION -> item -> DELTA-ELECTRON" and "-> graphics -> REPRESENTATION -> item -> AUGER-ELECTRON" while the photons are shown with "-> graphics -> REPRESENTATION -> item -> PHOTON". !Wul_end 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. 2 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: !Wol_start 1. From around the "-> &DRIFT -> SELECT"ed wires, a number of drift lines are computed (see "-> &DRIFT -> LINES") drifting them backwards from the wire. 2. The crossing points of these drift-lines are determined with a series of lines at an "-> &DRIFT -> XT-PLOT -> angle" to the y-axis and crossing the x-axis at regular intervals between "-> &DRIFT -> XT-PLOT -> xmin" and "-> &DRIFT -> XT-PLOT -> xmax" spaced by "-> &DRIFT -> XT-PLOT -> 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 "-> &DRIFT -> XT-PLOT -> 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 "-> &DRIFT -> XT-PLOT -> itermax") and which is declared to converge if the minimum drift time doesn't change much (see "-> &DRIFT -> XT-PLOT -> \ε"). 4. The results are printed (see "-> &DRIFT -> XT-PLOT -> PRINT-XT-RELATION"), plotted (see "-> &DRIFT -> XT-PLOT -> PLOT-XT-RELATION" and "-> &DRIFT -> XT-PLOT -> SCALE") and output to a dataset (see "-> &DRIFT -> XT-PLOT -> DATASET"). !Wol_end Note that there is another instruction in Garfield, "-> &DRIFT -> 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. !W
  -----------------------------------------------------------------------
  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
  -----------------------------------------------------------------------
!W
Format: !W
  XT-PLOT [DATASET "-> &DRIFT -> XT-PLOT -> DATASET -> file" ["-> &DRIFT -> XT-PLOT -> DATASET -> member"] [REMARK "-> &DRIFT -> XT-PLOT -> DATASET -> remark"] ...
          [ANGLE "-> &DRIFT -> XT-PLOT -> angle"] ...
          [X-RANGE "-> &DRIFT -> XT-PLOT -> xmin" "-> &DRIFT -> XT-PLOT -> xmax"] ...
          [X-STEP "-> &DRIFT -> XT-PLOT -> xstep"] ...
          [JUMP "-> &DRIFT -> XT-PLOT -> jump"] ...
          [ITERATIONS {YES|NO|"-> &DRIFT -> XT-PLOT -> itermax"}] ...
          [PRECISION "-> &DRIFT -> XT-PLOT -> \ε"] ...
          [LEFT-ANGLE-RANGE lmin lmax] ...
          [RIGHT-ANGLE-RANGE rmin rmax] ...
          ["-> &DRIFT -> XT-PLOT -> PRINT-XT-RELATION" | NOPRINT-XT-RELATION] ...
          ["-> &DRIFT -> XT-PLOT -> PLOT-XT-RELATION" | NOPLOT-XT-RELATION] ...
          ["-> &DRIFT -> XT-PLOT -> KEEP-RESULTS" | NOKEEP-RESULTS] ...
          [SCALE min max]
!W
Examples: !W
  xt-plot
  xt dataset lib.dat xt1 precision 1e-2
!W
(The second example will produce fairly quickly a crude x(t).) 3 DATASET Requests output of the x(t) relation to a dataset [no dataset is written by default]. 4 file The name of the "-> dataset -> structure -> file" in which you wish to write the x(t) relation. 4 member The name by which you will want to reference the "-> dataset -> structure -> member". 4 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. The default remark for x(t) relations states the wire number and the angle. 3 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\°.] 3 xmin Forms together with "-> &DRIFT -> XT-PLOT -> xmax" the range over which the x(t) relation is computed. [By default the whole x-range of the drift area is taken.] 3 xmax Forms together with "-> &DRIFT -> XT-PLOT -> xmin" the range over which the x(t) relation is computed. [By default the whole x-range of the drift area is taken.] 3 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.] 3 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.] 3 itermax The maximum number of iterations allowed. [Default: 5.] 3 \ε An accuracy parameter, to be adjusted with great care. [Default: 10\-4\.] 3 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\° both left and right.] 3 PRINT-XT-RELATION Requests a printout of the x(t) relation. [On by default.] 3 PLOT-XT-RELATION Requests a graph of the x(t) relation. The graph usually shows 2 curves: !Wul_start - a curve plotted with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" which shows the minimum drift time that has been found; - a curve plotted with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" which shows the integrated diffusion for the fastest drift-line. !Wul_end 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.] 3 KEEP-RESULTS If this option is selected, then the x(t) relations that have been obtained by XT-PLOT, will be stored as a set of matrices: !Wtable_start !T+P + + + . ------------------------------------------------- Global Description Units Type ------------------------------------------------- X_ Distance from electrode cm Matrix T_ Distance from electrode \μsec Matrix S_ Distance from electrode \μsec Matrix ------------------------------------------------- !Wtable_end The string "" in the global variable name is set to 1 for the first x(t) relation, 2 for the next etc. You have to declare the "-> Global" variables before the loop if !Wul_start - the instruction is placed in the body of a "-> Do" loop and - these global variables are used in arithmetic, in a condition of an "-> If_line" or a condition of an "-> If_block". !Wul_end Declaring is not required if the variables are only used outside the loop, in procedure "-> Call"s, in "-> Say" statements or for "-> algebra -> variables -> substitution" in normal input statements. [This option is not on by default, but its setting is remembered from one call to the next.] 3 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. 2 WRITE-ISOCHRONS Use this command to write out the coordinates of the points used for the isochrons as a result of the last "-> &DRIFT -> DRIFT" command. This statement should be issued after the DRIFT command. Format: !W
  WRITE-ISOCHRONS DATASET "-> &DRIFT -> WRITE-ISOCHRONS -> file" ["-> &DRIFT -> WRITE-ISOCHRONS -> member"] [REMARK "-> &DRIFT -> WRITE-ISOCHRONS -> remark"]
!W
Example: !W
  wr-iso 'test data b'
!W
(Writes the isochrons to the VM/CMS dataset TEST DATA on the users B disk.) 3 file The name of the "-> dataset -> structure -> file" in which you wish to write the isochrons. 3 member The name by which you will want to reference the "-> dataset -> structure -> member". 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. The field is left blank by default. 2 WRITE-TRACK Once a track has been prepared with "-> &DRIFT -> PREPARE-TRACK", it can be written to a dataset for later retrieval with "-> &DRIFT -> GET-TRACK". Format: !W
  WRITE-TRACK DATASET "-> &DRIFT -> WRITE-TRACK -> file" ["-> &DRIFT -> WRITE-TRACK -> member"] [REMARK "-> &DRIFT -> WRITE-TRACK -> remark"]
!W
Example: !W
  wr-tr 'disk$scratch:[pubzh.work.garfield]track.dat'
!W
3 file The name of the "-> dataset -> structure -> file" in which you wish to write the prepared track. 3 member The name by which you will want to reference the "-> dataset -> structure -> member" when retrieving it. 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. The field is left blank by default. 1 &SIGNAL Enters the section performing signal calculations. Since signal calculation and processing is strongly experiment dependent, this section consists only of a series of building blocks with which you can hopefully build a detailed simulation. A series of procedure calls, listed at the end of the "-> &SIGNAL -> overview", form an integral part of this section. 2 overview The instructions of the signal section fall in 5 categories: !Wul_start - setting various parameters - computing and processing signals - processing the signal - service instructions - debugging instructions - procedure calls !Wul_end Setting parameters: !Wtable_start !T+IP + . ------------------------------------------------------------------------- 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 RESET Resets one or more aspects of the signals SELECT Establishes the list of sense wires SIGNAL-PARAMETERS Signal calculation parameters TRACK Sets the track for which a signal is generated WINDOW Sets the time window of the signals ------------------------------------------------------------------------- !Wtable_end Computing and processing a signal: !Wtable_start !T+IP + . ------------------------------------------------------------------------- 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 ------------------------------------------------------------------------- !Wtable_end Service instructions: !Wtable_start !T+IP + . ------------------------------------------------------------------------- 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 ------------------------------------------------------------------------- !Wtable_end Debugging instructions: !Wtable_start !T+IP + . ------------------------------------------------------------------------- Command Short description ------------------------------------------------------------------------- CHECK Verify proper functioning PLOT-FIELD Plots the signal induction field ------------------------------------------------------------------------- !Wtable_end Procedure calls: !Wtable_start !T+P + . ---------------------------------------------------------------------------- Procedure Short description ---------------------------------------------------------------------------- Call "-> Call -> ADD_SIGNALS" Computes signals for current drift-line Call "-> Call -> GET_RAW_SIGNAL" Retrieves raw signals for an electrode Call "-> Call -> GET_SIGNAL" Retrieves the signals for an electrode Call "-> Call -> INDUCED_CHARGE" Computes integrated induced charge Call "-> Call -> LIST_RAW_SIGNALS" Lists raw signals currently in memory Call "-> Call -> STORE_SIGNAL" Stores a signal Call "-> Call -> THRESHOLD_CROSSING" Computes threshold crossing times Call "-> Call -> WEIGHTING_FIELD" Returns the weighting field Call "-> Call -> WEIGHTING_FIELD_3" Returns the weighting field ---------------------------------------------------------------------------- !Wtable_end 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. It is permissible to use the ADD-NOISE command before any signal has been computed, but the time "-> &SIGNAL -> WINDOW" must have been set beforehand. Format: !W
  ADD-NOISE NOISE-FUNCTION "-> &SIGNAL -> ADD-NOISE -> function"
!W
Example: !W
  add-noise noise-function -0.01*"-> algebra -> functions -> rnd_poisson"(30)
!W
In this example, the "-> algebra -> functions -> RND_POISSON" generator is used to add to each of the sampling points a Poisson distributed number with mean 30, multiplied by -0.01. 3 function The noise function can be a function of T, the time in \μsec corresponding to the signal sample. Such a dependence is of course not required. There is no default function, but the function is remembered 2 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 "-> &FIELD -> AREA" command of the field section. 2 AVALANCHE Chooses the probability distribution to be used for the avalanche multiplication factor, i.e. the number of electrons produced in the avalanche + the electron that started the avalanche. Electrons that are lost in attachment processes before reaching an electrode are included in the count. A multiplication factor of 1 means that there is no multiplication, factors smaller than 1 do not occur. No default type of avalanche is set - you must issue an AVALANCHE command prior to any signal calculation, each time you enter the &SIGNAL section. Only avalanches generated by electrons that hit an electrode (a wire, a plane, the tube, a solid) are affected by this statement. In particular, this command has no influence on avalanches in a field map for which no solids have been defined. This statement takes effect on "-> &SIGNAL -> SIGNAL" commands that follow. Issuing the AVALANCHE command does reset the signals that may have computed earlier. Format: !W
  AVALANCHE {"-> &SIGNAL -> AVALANCHE -> EXPONENTIAL" mean | ...
             "-> &SIGNAL -> AVALANCHE -> FIXED" factor | ...
             "-> &SIGNAL -> AVALANCHE -> FIXED-TOWNSEND" | ...
             "-> &SIGNAL -> AVALANCHE -> GAUSSIAN" mean relative_sigma | ...
             "-> &SIGNAL -> AVALANCHE -> NONE" | ...
             "-> &SIGNAL -> AVALANCHE -> POLYA-FIXED" [mean [theta]] | ...
             "-> &SIGNAL -> AVALANCHE -> POLYA-TOWNSEND" [theta] | ...
             "-> &SIGNAL -> AVALANCHE -> TOWNSEND"}
!W
Examples: !W
  aval exp 1e4
  aval townsend
!W
3 EXPONENTIAL The multiplication factors are distributed exponentially with a mean (and also an RMS) equal to "mean". For large mean multiplications, significant deviations are observed, especially at the low end high ends of the distribution. These can empirically be modeled with the Polya distribution which can be obtained by using "-> &SIGNAL -> AVALANCHE -> POLYA-FIXED" or "-> &SIGNAL -> AVALANCHE -> POLYA-TOWNSEND" Although the exponential distribution has a non-zero probability at 0, the multiplication factor used in Garfield is always equal to at least 1: if a factor less than 1 is drawn, it is rejected and a new number is drawn. The mean multiplication factor has to be strictly positive. [Default: you have to specify the mean multiplication.] 3 FIXED Results in a fixed multiplication by the factor that you specify. The factor has to be larger than or equal to 1, the latter being equivalent to specifying "-> &SIGNAL -> AVALANCHE -> NONE". [Default: none, you have to specify the multiplication factor.] 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. This option is accessible only if Townsend data has been entered in the gas section. 3 GAUSSIAN Not a physical choice for a single avalanche but sometimes used when many exponentially distributed avalanches overlap, resulting actually in a \Γ-distribution. Please note that the 2nd argument is a relative, not an absolute, standard deviation. If you use for instance !W
  avalanche gaussian 20000 0.5
!W
then you'll end up with a normally distributed multiplication with a mean of 20000 and a sigma of 10000. The Gaussian distribution has non-zero probability for factors less than 0. Since the multiplication factor as defined here has to be equal to 1 at least, Garfield will if needed repeatedly draw a random number until an acceptable number is found. The mean is allowed to be negative, but the width must be strictly positive - a width of zero would be equivalent to using the "-> &SIGNAL -> AVALANCHE -> FIXED" option. [Default: none, you have to specify both the mean and the relative standard deviation.] 3 NONE States that there is no multiplication process. 3 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 \θ. The Polya distribution is a \Γ-distribution that matches reasonably well the fluctuations in a cylindrically symmetric amplification region. A physical interpretation of the parameter \θ is given in G.\ D.\ Alkhazov, NIM\ 89 (1970) 155-165. When \θ is set to 0, an exponential distribution is obtained. If \θ\ <\ 0, the distribution is "concave", while for \θ\ >\ 0 the distribution assumes the more usual shape with a maximum. The properties of this distribution can be examined using the "-> algebra -> functions -> RND_POLYA" function, as shown in the following example: !W
  "-> Say" "Please enter theta"
  "-> Parse" Terminal theta
  Call "-> Call -> book_histogram"(ref,100,0.0,5.0)
  For i From 1 To 50000 Do
     Call "-> Call -> fill_histogram"(ref,"-> algebra -> functions -> rnd_polya"(theta))
  Enddo
  !"-> graphics -> options" log-y
  Call "-> Call -> plot_histogram"(ref,`Multiplication`,`Polya distribution`)
  Call "-> Call -> plot_end"
!W
Although the Polya distribution has a non-zero probability at 0, the multiplication factor used in Garfield is always equal to at least 1. If a factor less than 1 is drawn, it is rejected and a new number is drawn. The mean multiplication factor has to be strictly positive, [The default value for the mean multiplication is 1, the default setting of the \θ parameter is 0.5.] 3 POLYA-TOWNSEND The mean multiplication is obtained by integrating the Townsend coefficient over the current drift-line and the fluctuations are according to a Polya distribution with parameter \θ. See "-> &SIGNAL -> AVALANCHE -> POLYA-FIXED" for comments on the Polya distribution. Additional fluctuations are obtained when the Monte Carlo drift line integration routines are used since these introduce variations in the drift path. Although the Polya distribution has a non-zero probability at 0, the multiplication factor used in Garfield is always equal to at least 1. If a factor less than 1 is drawn, it is rejected and a new number is drawn. This option is accessible only if Townsend data has been entered in the gas section. [The default value for \θ is 0.5.] 3 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 "-> &SIGNAL -> AVALANCHE -> EXPONENTIAL" option, but here the mean of the distribution may be different for each ionisation cluster. Additional fluctuations are obtained when the Monte Carlo drift-line integration routines are used since these introduce variations in the drift path. Although the exponential distribution has a non-zero probability at 0, the multiplication factor used in Garfield is always equal to at least 1. If a factor less than 1 is drawn, it is rejected and a new number is drawn. This option is accessible only if Townsend data has been entered in the gas section. 2 CHECK A debugging instruction, checking signal related routines. Format: !W
  CHECK [AVALANCHE] ...
        [DIFFUSION] ...
        [CLUSTER] ...
        [RANGE min max] ...
        [FROM x y] ...
        [N n] ...
        [BINS nbin]
!W
Example: !W
  ch avalanche from 5 6 bins 50
!W
2 CONVOLUTE-SIGNALS Once "-> &SIGNAL -> SIGNAL" has computed the currents induced in the electrodes of the chamber, they would normally be written out with "-> &SIGNAL -> WRITE-SIGNALS" for further processing !D1 by programs like Spice (see http://wwwinfo.cern.ch/ce/ae/Pspice/). !Wby programs like Spice. Signal processing in Garfield is limited to convoluting the induced currents with transfer functions and to addition of certain types of noise with "-> &SIGNAL -> 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. It is permissible to use the CONVOLUTE-SIGNALS command before any signal has been computed, e.g. in order to process noise, but the time "-> &SIGNAL -> WINDOW" must have been set beforehand. Format: !W
  CONVOLUTE-SIGNALS ...
       "-> &SIGNAL -> CONVOLUTE-SIGNALS -> TRANSFER-FUNCTION" { function  |  transfer VS time } ...
       ["-> &SIGNAL -> CONVOLUTE-SIGNALS -> ADD-ON-FUNCTION" add] ...
       "-> &SIGNAL -> CONVOLUTE-SIGNALS -> RANGE" tmin tmax
!W
Example: !W
  convolute-signals ...
       transfer-function 250*(6*t/0.025)^6*"-> algebra -> functions -> exp"(-6*t/0.025) ...
       range 0 2000
!W
(This example, taken from an Atlas muon tube study, simulates the response of a pre-amplifier.) 3 TRANSFER-FUNCTION The transfer function, which can be specified in either of two ways: !Wul_start - As a function that depends on the time T, in \μsec. - As a set of two matrices separated by the word 'VS', the first is the values of the transfer function for the times listed in the second matrix. !Wul_end There is no default transfer function, but the transfer function is remembered from one call to the next. 3 ADD-ON-FUNCTION Some transfer functions contain, in the time domain, a \δ-distribution term. This is for instance the case of pole/zero filters which have as transfer functions (modulo overall constant factors): !W
         s + 1/t1
  F(s) = -------- ,   F(t) = (1/t1 - 1/t2) * exp(-t/t2) + \δ(t)
         s + 1/t2
!W
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 !W
  convolute transfer-function 0.2*"-> algebra -> functions -> exp"(-t/0.012) add signal
!W
[By default, no function is added.] 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 extends from 0 to 10\10\\ \μsec.] 2 FOURIER In chambers which are periodic, the field is identical in all copies of the basic cell, but the signals induced in the wires of one copy are as a rule are not the same as the signals induced in the wires of another copy. Garfield will, by default, compute the weighting fields by considering only the basic cell - suppressing all periodicities. This is a good approximation if the wires that are read-out are surrounded by many other wires in the basic cell. If this is not the case, then the FOURIER command can be used to request inclusion of a number of copies of the basic cell. For technical reasons related to the Fourier transforms needed for such calculations, the number of copies to be considered must be an integral power of 2. Signal calculations with a large number of copies of the basic cell requires considerable memory - temporary files on disk will be used for the purpose. Requesting a large number of copies is meaningful only in chambers which contain equipotential planes - convergence is poor otherwise. In addition to numeric arguments, the value NONE can be specified. This is to be used in the exceptional case where all copies of the read-out wires are interconnected. The weighting field will then be computed using the same potential functions that are used for the electric field. In addition, avalanches will be started from the copy in the basic cell, of the wire where an electron ends. As a result, the plot produced in response to the "-> &SIGNAL -> OPTIONS -> CLUSTER-PLOT" option, may be surprising. This statement takes effect on "-> &SIGNAL -> SIGNAL" commands that follow. Issuing the FOURIER command does reset the signals that may have computed earlier. Format: !W
  FOURIER [ copies | NONE ]
!W
Example: !W
  fourier 16
!W
(Note that this setting may require a fantastic amount of disk I/O !) 2 GET-TRACK Retrieves a prepared track from a dataset with "-> &DRIFT -> WRITE-TRACK". Format: See the "-> &DRIFT -> GET-TRACK" command in the drift section. 2 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 "-> &SIGNAL -> PLOT-FIELD" instruction. The grid is common to all sections. Format: !W
  GRID  "-> &SIGNAL -> GRID -> number"_of_steps_in_x  [number_of_steps_in_y]
!W
Example: !W
  grid 25 15
!W
3 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 \φ) spacing. [Default is 25 for both.] 2 INTEGRATION-PARAMETERS See the "-> &DRIFT -> INTEGRATION-PARAMETERS" command in the drift section. 2 OPTIONS In addition to the top level "-> OPTIONS", and the "-> &DRIFT -> OPTIONS" of the drift section, the following options related to signal calculations are available: Format: !W
  OPTIONS [ "-> &SIGNAL -> OPTIONS -> CLUSTER-PRINT" | NOCLUSTER-PRINT ] ...
          [ "-> &SIGNAL -> OPTIONS -> CLUSTER-PLOT" | NOCLUSTER-PLOT ] ...
          [ "-> &SIGNAL -> OPTIONS -> CONTOUR-ALL-MEDIA" | "-> &SIGNAL -> OPTIONS -> CONTOUR-DRIFT-MEDIUM" ] ...
          [ NOWIRE-MARKERS | "-> &SIGNAL -> OPTIONS -> WIRE-MARKERS" ] ...
          [ NOCHECK-MAP-INDICES | "-> &SIGNAL -> OPTIONS -> CHECK-MAP-INDICES" ]
!W
Example: !W
  opt nocluster-print
!W
3 CLUSTER-PLOT Requests that, while "-> &SIGNAL -> 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. When "-> &SIGNAL -> FOURIER" is set to NONE, ions may appear to start from another periodic copy of a wires than the copy where the electrons arrive. The electron drift-lines are plotted with representation "-> graphics -> REPRESENTATION -> item -> E-DRIFT-LINE", the ions with "-> graphics -> REPRESENTATION -> item -> ION-DRIFT-LINE". The various elements of the track are shown with their respective "-> &DRIFT -> TRACK -> representations". [This option is initially on.] 3 CLUSTER-PRINT Requests printing of a table of clusters. On certain systems, the graphics and printed output appear on the same screen. If both "-> &SIGNAL -> OPTIONS -> 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.] 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.] 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.] 3 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 "-> &CELL -> OPTIONS -> WIRE-MARKERS" option in the cell section. 3 CHECK-MAP-INDICES Requests a verification of the map index calculation. See the "-> &FIELD -> OPTIONS -> CHECK-MAP-INDICES" option in the field section for further information. 2 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 "-> &SIGNAL -> PLOT-FIELD -> functions -> weighting_field" and the "-> &SIGNAL -> PLOT-FIELD -> functions -> charges" induced in an electrode by electrons and ions drifting from a given point. The weighting field and the induced charge are plotted separately 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: !W
  PLOT-FIELD ["-> &SIGNAL -> PLOT-FIELD -> CONTOUR" [f1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                             [N n] ...
                             [LABELS | NOLABELS]] ...
             ["-> &SIGNAL -> PLOT-FIELD -> GRAPH" [f2]     [ON f_curve] ...
                             [N n]] ...
                             [SCALE min max] ...
                             [NOPRINT | PRINT] ...
             ["-> &SIGNAL -> PLOT-FIELD -> HISTOGRAM" [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                             [BINS nbin]] ...
             ["-> &SIGNAL -> PLOT-FIELD -> SURFACE" [f4]   [ANGLES \φ \θ]] ...
             ["-> &SIGNAL -> PLOT-FIELD -> VECTOR" [f5 f6]] ...
             ["-> &SIGNAL -> PLOT-FIELD -> GROUP" {ALL | sense }] ...
             ["-> &SIGNAL -> PLOT-FIELD -> TIME-WINDOW" tmin tmax] ...
             ["-> &SIGNAL -> PLOT-FIELD -> RUNGE-KUTTA-DRIFT-LINES" | "-> &SIGNAL -> PLOT-FIELD -> MONTE-CARLO-DRIFT-LINES"]
!W
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: !W
  plot-field hist status_e vector surf cont
  plot-field contour time_ion range 1000 3000
!W
(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.) 3 functions All functions in the description of the PLOT-FIELD command (f1,\ f2\ ...\ f6) may depend on the following set of variables: !Wtable_start !T+P + + . ------------------------------------------------------------------------ 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 - ------------------------------------------------------------------------ !Wtable_end Other variables can be added on request. 4 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 "-> &SIGNAL -> PLOT-FIELD -> GROUP" keyword. You can limit the charge integration to a time window by means of the "-> &SIGNAL -> PLOT-FIELD -> TIME-WINDOW" keyword. 4 status The numeric "-> &DRIFT -> methods -> status" codes indicate where the particle ended up. They have a 1-1 correspondence with the status strings displayed in regular program output. 4 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 \μsec. 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. 3 CONTOUR Produces a plot of the lines of equal function values. Contours are drawn in the part of the viewing "-> &FIELD -> AREA -> plane" that is located within the current "-> &SIGNAL -> AREA" box. The contours are labelled 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. Contours are plotted starting from their crossings with a regular "-> &SIGNAL -> GRID" covering the AREA. Very small contours are not found if the grid is course. It is therefore usually preferable to use a fine grid for contours, even though plotting the contours takes more time. You may also wish to optimise the "-> graphics -> CONTOUR-PARAMETERS", especially if your AREA is very small or highly non-isometric. The contours are drawn with the representation "-> graphics -> REPRESENTATION -> item -> CONTOUR-NORMAL" and are labelled with "-> graphics -> REPRESENTATION -> item -> 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.] 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 "-> &SIGNAL -> 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 "-> introduction -> quotes", e.g. !W
  '"-> algebra -> functions -> cos"(pi*t),"-> algebra -> functions -> sin"(pi*t),0'
!W
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. Re-routing 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.] 3 HISTOGRAM The function is sampled over a "-> &SIGNAL -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &SIGNAL -> 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 "-> Call -> BOOK_HISTOGRAM -> options -> 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.] 3 SURFACE The function is sampled over a "-> &SIGNAL -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &SIGNAL -> AREA" box. The function values are presented as a three dimensional plot. The plot is first rotated by \φ degrees around the z-axis and then tilted by \θ 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\°. The viewing angles are remembered from one call to the next.] 3 VECTOR This plot shows the flow of a 3-vector sampled on a "-> &SIGNAL -> GRID" of points in the part of the current viewing "-> &FIELD -> AREA -> plane" that is located inside the "-> &SIGNAL -> AREA" box. The vectors are projected onto the current viewing plane. The z-component is set to 0, if not explicitly 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 "-> graphics -> REPRESENTATION -> item -> FUNCTION-1" representation. The appearance of the arrow is influence by the "-> graphics -> ARROW-TIP-ANGLE" and "-> graphics -> ARROW-TIP-LENGTH" settings. [The default functions are EWX, EWY, EWZ, i.e. the weighting field.] 3 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed. [By default, all sense wire groups are plotted.] 3 TIME-WINDOW Specifies the time window over which the "-> &SIGNAL -> PLOT-FIELD -> functions -> 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.] 3 RUNGE-KUTTA-DRIFT-LINES Requests the use of the "-> &DRIFT -> methods -> 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 controlling the accuracy are adjusted for chambers that are several centimetres large. When studying much smaller structures, at the \μm scale, one may wish to request more "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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-LINES.] 3 MONTE-CARLO-DRIFT-LINES Requests "-> &DRIFT -> methods -> Monte_Carlo" calculation of a drift path, instead of a "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration. This option is particularly interesting used in conjunction with drifting from a "-> &DRIFT -> DRIFT -> TRACK" and on which clusters are generated with "-> &DRIFT -> TRACK -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" as set with the "-> &DRIFT -> INTEGRATION-PARAMETERS" command. [The initial default is RUNGE-KUTTA-DRIFT-LINES.] 2 PLOT-SIGNALS Plots the signals that have been computed earlier, usually by a "-> &SIGNAL -> SIGNAL" command or by calls to "-> Call -> ADD_SIGNALS". The graphs contain either one or two curves, distinguished by their "-> &SIGNAL -> PLOT-SIGNALS -> representations", depending on whether cross induced currents have been computed or not. Use the "-> &SIGNAL -> SELECT" statement without arguments to find out which electrodes are concerned by each of the signals. Format: !W
  PLOT-SIGNALS ["-> &SIGNAL -> PLOT-SIGNALS -> TIME-WINDOW" {AUTOMATIC | tmin tmax}] ...
               ["-> &SIGNAL -> PLOT-SIGNALS -> RANGE" {AUTOMATIC | smin smax}] ...
               ["-> &SIGNAL -> PLOT-SIGNALS -> WIRES" {ALL | ACTIVE | numbers, labels}] ...
               ["-> &SIGNAL -> PLOT-SIGNALS -> CROSS-INDUCED-SIGNALS" | NOCROSS-INDUCED-SIGNALS] ...
               ["-> &SIGNAL -> PLOT-SIGNALS -> DIRECT-SIGNALS" | NODIRECT-SIGNALS]
!W
Example: !W
  pl-sig time 2.7 3.1 wire 1
!W
Plots the signal on wire 1 in the time window [2.7,3.1]\ \μsec. 3 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. 3 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.] 3 WIRES Normally, all non-zero currents on the "-> &SIGNAL -> SELECT"ed 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. 3 CROSS-INDUCED-SIGNALS Requests that the cross induced currents, if available, are shown. [By default, these currents are shown if available.] 3 DIRECT-SIGNALS Requests that the direct currents are shown. [This is the case, by default.] 3 representations The direct current is shown with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", the cross induced current with representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-2". 2 PREPARE-TRACK Track preparation is a required step when using the "-> &SIGNAL -> SIGNAL -> INTERPOLATE-TRACK" option of the "-> &SIGNAL -> SIGNAL" command. Format: See "-> &DRIFT -> PREPARE-TRACK" in the drift section. 2 REPEAT !W
This statement has been withdrawn. !W
The REPEAT statement used to tell the SIGNAL command that you wish to repeat the calculation several times. !W
  Old format:        New format:

  REPEAT 100         For i From 1 To 100 Do
  SIGNAL             SIGNAL
                     Enddo
!W
2 RESET Resets selectively the signals, the time window, the avalanche model and the signal matrices. If the statement is issued without arguments, then all elements are reset. Format: !W
  RESET   ["-> &SIGNAL -> RESET -> AVALANCHE-MODEL"] ...
          ["-> &SIGNAL -> RESET -> MATRICES"] ...
          ["-> &SIGNAL -> RESET -> SIGNALS"] ...
          ["-> &SIGNAL -> RESET -> WINDOW"] 
!W
3 AVALANCHE-MODEL Resets the currently selected avalanche model. Further signal calculations can only be performed after an "-> &SIGNAL -> AVALANCHE" statement has been issued. 3 MATRICES Resets the matrices used to compute induced currents. A new set of matrices will be computed when needed. This option is intended for debugging purposes only, the signal matrices normally do not change during signal calculations and are normally updated when a change in parameters makes this mandatory. 3 SIGNALS Resets the signals, both the direct component and the cross induced component, of all electrodes to zero. 3 WINDOW Resets the current time window. Further signal calculations can only be performed after a "-> &SIGNAL -> WINDOW" statement has been issued. 2 RESOLUTION This command has been renamed "-> &SIGNAL -> WINDOW". 2 SELECT Selects and groups the electrodes for which signals are to be computed when issuing a "-> &SIGNAL -> SIGNAL" command and when calling the "-> Call -> ADD_SIGNALS", "-> Call -> AVALANCHE_SIGNAL" and related procedures. This command, and the resulting selection of electrodes, is common throughout Garfield, but the interpretation of the selection is left to the individual instructions. In this section, the grouping is relevant: the signals for electrodes in a single group are summed. This command takes effect at the next signal calculation. Issuing a SELECT causes all previously computed signals to be deleted. Similarly, the "-> &SIGNAL -> SIGNAL -> ADD" option of the "-> &SIGNAL -> SIGNAL" command can not be used on the first signal that is computed after a SELECT command. A SELECT command without arguments will display the contents of the electrode groups. This is helpful when figuring out what the signals produced by "-> &SIGNAL -> PLOT-SIGNALS" correspond to. It is also useful in conjunction with the "-> Call -> GET_SIGNAL" procedure. The cell section establishes an initial selection of all electrodes which have a label S, without grouping. Format: See "-> &FIELD -> SELECT" Example: !W
  sel (1 s) 2 f
!W
(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.) 2 SIGNAL This instruction computes the signals on the electrodes in the chamber that result from the passage of a charged particle. Before issuing a SIGNAL instruction, one has to !Wul_start - set the drift "-> &SIGNAL -> AREA"; - set both the geometrical parameters and the clustering model of the "-> &SIGNAL -> TRACK"; - set the "-> &SIGNAL -> AVALANCHE" model; - set the time "-> &SIGNAL -> WINDOW" over which signals are to be computed, and - "-> &SIGNAL -> SELECT" the electrodes to be read out. !Wul_end Further, it is advisable to use the "-> &SIGNAL -> OPTIONS -> CLUSTER-PLOT" option for the first few signals to inspect the electron and ion trajectories. This will tell you whether the "-> &SIGNAL -> AREA" is sufficiently large and whether the "-> &SIGNAL -> INTEGRATION-PARAMETERS" are properly set. Signals can be further processed externally with electronics simulation programs ("-> &SIGNAL -> WRITE-SIGNALS"). Inside Garfield, one can do basic signal manipulations such as convolution with transfer functions ("-> &SIGNAL -> CONVOLUTE-SIGNALS"), adding noise ("-> &SIGNAL -> ADD-NOISE") and determining threshold crossings ("-> Call -> 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. Procedure calls should be used if greater flexible is required. "-> Call -> ADD_SIGNALS" is the key procedure: it computes the currents induced by a single charged particle. Use "-> Call -> INDUCED_CHARGE" to compute the charge (as opposed to current) induced by a single charged particle. Format: !W
  SIGNAL ["-> &SIGNAL -> SIGNAL -> ANGULAR-INTEGRATION-POINTS" n_angle] ...
         ["-> &SIGNAL -> SIGNAL -> ANGULAR-SPREAD" {f_angle | FLAT} | NOANGULAR-SPREAD] ...
         ["-> &SIGNAL -> SIGNAL -> ATTACHMENT" | NOATTACHMENT] ...
         ["-> &SIGNAL -> SIGNAL -> AVALANCHE" | NOAVALANCHE] ...
         ["-> &SIGNAL -> SIGNAL -> AVERAGE-SIGNAL" n_average | "-> &SIGNAL -> SIGNAL -> SAMPLE-SIGNAL" | "-> &SIGNAL -> SIGNAL -> SUM-SIGNAL"] ...
         ["-> &SIGNAL -> SIGNAL -> DIFFUSION" | NODIFFUSION] ...
         ["-> &SIGNAL -> SIGNAL -> ELECTRON-PULSE" | NOELECTRON-PULSE] ...
         ["-> &SIGNAL -> SIGNAL -> ION-PULSE" | NOION-PULSE] ...
         ["-> &SIGNAL -> SIGNAL -> INTERPOLATION-ORDER" n_order] ...
         ["-> &SIGNAL -> SIGNAL -> ION-ANGLES" {n_ion | NOSAMPLING}] ...
         ["-> &SIGNAL -> SIGNAL -> ION-TAIL" | "-> &SIGNAL -> SIGNAL -> DETAILED-ION-TAIL" | ...
          "-> &SIGNAL -> SIGNAL -> NONSAMPLED-ION-TAIL" | NOION-TAIL] ...
         ["-> &SIGNAL -> SIGNAL -> ION-THRESHOLD" thr] ...
         ["-> &SIGNAL -> SIGNAL -> RUNGE-KUTTA-DRIFT-LINES" | "-> &SIGNAL -> SIGNAL -> MONTE-CARLO-DRIFT-LINES"] ...
         ["-> &SIGNAL -> SIGNAL -> NEW" | "-> &SIGNAL -> SIGNAL -> ADD"] ...
         [NOCROSS-INDUCED | "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED"] ...
         [NOINTERPOLATE-TRACK | "-> &SIGNAL -> SIGNAL -> INTERPOLATE-TRACK"]
!W
Example: !W
  signal cross-induced
!W
3 ADD Signals from repeated simulations will be summed, electrode by electrode. This option is the reverse of "-> &SIGNAL -> SIGNAL -> NEW". This option can for instance be used to study two-track resolution. In order to prevent summing of signals computed with different characteristics, one may not use the ADD option with the first signal after: !Wul_start - issuing a "-> &SIGNAL -> SELECT" statement; - issuing a "-> &SIGNAL -> WINDOW" statement; - changing the setting of "-> &SIGNAL -> SIGNAL -> ION-ANGLES"; - switching on or off the "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED" option. !Wul_end [By default, signals are not summed. The option is reset to NEW at each signal calculation.] 3 ANGULAR-INTEGRATION-POINTS When computing the weight assigned by the "-> &SIGNAL -> SIGNAL -> ANGULAR-SPREAD" function to each of the "-> &SIGNAL -> SIGNAL -> ION-ANGLES", the function is integrated using the Newton-Raphson technique with 2*n_angle+1 points. Use of this keyword implies the "-> &SIGNAL -> SIGNAL -> ION-TAIL" model of ion tail calculation. [By default, n_angle is set to 2.] 3 ANGULAR-SPREAD In the "-> &SIGNAL -> SIGNAL -> 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 "-> &SIGNAL -> SIGNAL -> ION-ANGLES". The function that you specify is integrated around the nearest angles using Newton-Raphson integration with "-> &SIGNAL -> SIGNAL -> 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: !W
  "-> Global" sigma 30
  "-> &SIGNAL -> signal" cross ion-angles 1000 ang-spread '"-> algebra -> functions -> exp"(-((phi*180/(pi*{sigma}))^2))'
!W
This example assumes a Gaussian angular spread with a sigma of 30\°. The number of discretisation points is set to 1000 in this example. References: !W
!W
[1] !W
G. Charpak et al., NIM 148 (1978) 471-482 !W
[2] !W
T.J. Harris & E. Mathieson, NIM 154 (1978) 183-188 !W
[3] !W
E. Mathieson & T.J. Harris, NIM 159 (1979) 483-187 !W
[4] !W
Harry van der Graaf, PhD thesis, TU Delft (1986) !W
[5] !W
H. van der Graaf & J.P. Wagenaar, NIM A252 (1986) 311-320 !W
!D4 G. Charpak et al., NIM 148 (1978) 471-482 T.J. Harris & E. Mathieson, NIM 154 (1978) 183-188 E. Mathieson & T.J. Harris, NIM 159 (1979) 483-187 Harry van der Graaf, PhD thesis, TU Delft (1986) 3 ATTACHMENT Attachment coefficients will be taken into account for signal calculations. They occur at two instances: !Wul_start - as a multiplicative constant applied to the multiplication distribution that has been specified with the "-> &SIGNAL -> AVALANCHE" command; - when tracing the avalanche step-by-step during the computation of the "-> &SIGNAL -> SIGNAL -> ELECTRON-PULSE" and the "-> &SIGNAL -> SIGNAL -> DETAILED-ION-TAIL". !Wul_end Attachment coefficients are taken into account by simply multiplying the multiplication factor computed from Townsend coefficients with the loss factor computed from attachment coefficients. This leads to incorrect statistics: an electron lost through attachment will not be able to multiply later, while an electron that has already multiplied will usually only be partially lost through attachment. This asymmetry is important since in many gas mixtures the attachment coefficients dominate the Townsend coefficient at fields slightly smaller than those found at the onset of multiplication. For gas mixtures in which attachment is important, it is therefore advisable to use the "-> Call -> AVALANCHE_SIGNAL" procedure instead of the SIGNAL command. This option can only be specified if attachment data has been entered in the gas section. [This option is initially on and is remembered from one SIGNAL statement to the next.] 3 AVALANCHE Enables the avalanche setting chosen with "-> &SIGNAL -> AVALANCHE". NOAVALANCHE leads to a fixed multiplication factor of 1, which means that no additional electrons are produced during the avalanche process. [This option is initially on and is remembered from one SIGNAL statement to the next.] 3 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 centred at the point in time indicated in the output, interpolating the signal vector with a polynomial order set with "-> &SIGNAL -> SIGNAL -> INTERPOLATION-ORDER". This parameter can also be set with the "-> &SIGNAL -> SIGNAL-PARAMETERS" command. [By default, 5 points are used, i.e. n_average is set to 2.] 3 CROSS-INDUCED 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" or "cross induced". If the field is derived from a field map, then the classification of signals is based on the solids. In the absence of solids, there are only indirect signals. Direct and indirect signals are shown separately by "-> &SIGNAL -> PLOT-SIGNALS", they can also separately be retrieved by the "-> Call -> GET_SIGNAL" procedure. When the CROSS-INDUCED option is on, Garfield computes both the direct and the indirect currents in all electrodes that are currently "-> &SIGNAL -> SELECT"ed for read-out. When CROSS-INDUCED is off, then Garfield computes only the direct signals. [The option is initially switch on.] 3 DETAILED-ION-TAIL Adds the current induced by avalanche ions, computed signal according to a model in which the ions start drifting from the point where they are on average produced in the multiplication process of the primary electron. In this model, the avalanche develops along the path of the primary electron. A mean avalanche profile is computed from the Townsend and attachment coefficients. This profile is scaled to a size as given by the "-> &SIGNAL -> AVALANCHE" command, which also determines the fluctuations. Point-to-point correlations in the avalanche size are absent in this model. This model is to be preferred 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 "-> &SIGNAL -> SIGNAL -> ION-TAIL" and "-> &SIGNAL -> SIGNAL -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" off. Use the "-> Call -> AVALANCHE_SIGNAL" procedure if the lateral extent of the avalanche is of importance and if you wish to have a more accurate growth model. [The default is ION-TAIL.] 3 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.] 3 ELECTRON-PULSE Adds the signal due to the movement of the ionisation electrons. 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 "-> &SIGNAL -> SIGNAL -> INTERPOLATE-TRACK" option is not compatible with ELECTRON-PULSE. [An electron pulse is by default not included.] 3 ION-PULSE Adds the signal due to the movement of the ionisation ions. The ion pulse is computed by tracing the ionisation electrons from their production point. The model currently doesn't foresee multiplication processes along the ion path. As a result, the signal due to this process is negligibly small in all chambers where amplification of the primary electrons occurs. Signals due to primary ions are classified as cross-induced and you therefore have to ensure the "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED" flag is on when setting the ION-PULSE option. [An ion pulse is by default included.] 3 INTERPOLATE-TRACK Enables the use of the prepared track, see "-> &SIGNAL -> PREPARE-TRACK". This option can not be used together with "-> &SIGNAL -> SIGNAL -> ELECTRON-PULSE" nor with "-> &SIGNAL -> SIGNAL -> DETAILED-ION-TAIL". [Default: Even if a prepared track is available, it will by default not be used for the signal calculation.] 3 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 n_average parameter is set with the "-> &SIGNAL -> SIGNAL -> AVERAGE-SIGNAL" option. 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. This parameter can also be set with the "-> &SIGNAL -> SIGNAL-PARAMETERS" command. [A value of 1 is therefore recommended, and is also default.] 3 ION-ANGLES When the "-> &SIGNAL -> SIGNAL -> 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: !Wul_start - similar ion tails are needed for electrons from possibly many clusters, thus a considerable amount of CPU time is saved; - the ion tail shape usually doesn't vary much between nearby electron incidence angles. !Wul_end 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 "-> &SIGNAL -> SIGNAL -> 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 occurring 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] 3 ION-TAIL Adds the current induced by avalanche ions, 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 "-> &SIGNAL -> SIGNAL -> 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 "-> &SIGNAL -> SIGNAL -> ION-ANGLES". If such sampling is not desired, then you should opt for the "-> &SIGNAL -> SIGNAL -> 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. "-> &SIGNAL -> SIGNAL -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" off. [This is the default.] 3 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 "-> &SIGNAL -> SIGNAL -> DETAILED-ION-TAIL" model. [The fraction is initially set to 0.] 3 MONTE-CARLO-DRIFT-LINES Uses the "-> &DRIFT -> methods -> Monte_Carlo" drifting routines rather the default "-> &DRIFT -> methods -> 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 "-> &SIGNAL -> SIGNAL -> INTERPOLATE-TRACK" can not be used in conjunction with MONTE-CARLO-DRIFT-LINES, use of this option tends to make the computations longer. You may have to adjust the Monte Carlo parameters in the "-> &DRIFT -> INTEGRATION-PARAMETERS" statement when using this option. [Default is RUNGE-KUTTA-DRIFT-LINES] 3 NEW Means that summing of signals over repeated simulations does not take place. This option is the reverse of "-> &SIGNAL -> SIGNAL -> ADD". [This is default.] 3 NONSAMPLED-ION-TAIL A variant of the "-> &SIGNAL -> SIGNAL -> ION-TAIL" model, in which the avalanche 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 "-> &SIGNAL -> SIGNAL -> 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 "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" off. [The default is ION-TAIL.] 3 RUNGE-KUTTA-DRIFT-LINES Requests the use of the "-> &DRIFT -> methods -> 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 controlling the accuracy are adjusted for chambers that are several centimetres large. When studying much smaller structures, at the \μm scale, one may wish to request more "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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-LINES.] 3 SAMPLE-SIGNAL If this option is switched on, then 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, which may lead to incorrect integrated currents. Also, the signal when summed will not be normalised. This parameter can also be set with the "-> &SIGNAL -> SIGNAL-PARAMETERS" command. [By default, AVERAGE-SIGNAL is used with 5-point integration.] 3 SUM-SIGNAL If this option is switched on, then the signal between integration steps is assumed to be constant. The signals will be correctly normalised to the extent that this assumption holds. This is the appropriate setting for "-> &DRIFT -> methods -> Monte_Carlo" and and "-> &DRIFT -> methods -> microscopic" drift line integration, but not for "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration. [By default, AVERAGE-SIGNAL is used with 5-point integration.] 2 SIGNAL-PARAMETERS Sets parameters used for the calculation and interpolation of signals. These parameters can also be set via the "-> &SIGNAL -> SIGNAL" command. Format: !W
  SIGNAL-PARAMETERS ["-> &SIGNAL -> SIGNAL-PARAMETERS -> AVERAGE-SIGNAL" n_average | "-> &SIGNAL -> SIGNAL-PARAMETERS -> SAMPLE-SIGNAL" | "-> &SIGNAL -> SIGNAL-PARAMETERS -> SUM-SIGNAL"] ...
                    ["-> &SIGNAL -> SIGNAL-PARAMETERS -> INTERPOLATION-ORDER" n_order] ...
                    ["-> &SIGNAL -> SIGNAL-PARAMETERS -> INTEGRATE-WEIGHTING-FIELD" | "-> &SIGNAL -> SIGNAL-PARAMETERS -> SAMPLE-WEIGHTING-FIELD"]
!W
3 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 centred at the point in time indicated in the output, interpolating the signal vector with a polynomial order set with "-> &SIGNAL -> SIGNAL -> INTERPOLATION-ORDER". [By default, 5 points are used, i.e. n_average is set to 2.] 3 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 n_average parameter is set with the "-> &SIGNAL -> SIGNAL -> AVERAGE-SIGNAL" option. 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.] 3 SAMPLE-SIGNAL If this option is switched on, then 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, which may lead to incorrect integrated currents. Also, the signal when summed will not be normalised. [By default, AVERAGE-SIGNAL is used with 5-point integration.] 3 SUM-SIGNAL If this option is switched on, then the signal between integration steps is assumed to be constant. The signals will be correctly normalised to the extent that this assumption holds. This is the appropriate setting for "-> &DRIFT -> methods -> Monte_Carlo" and and "-> &DRIFT -> methods -> microscopic" drift-line integration, but not for "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration. [By default, AVERAGE-SIGNAL is used with 5-point integration.] 3 INTEGRATE-WEIGHTING-FIELD Only used with "-> &DRIFT -> methods -> microscopic" drift-line integration. Requests 6-point Gaussian integration of the weighting field over a drift-path segment when computing the induced current. This is considerably more precise in case long steps are taken because of sparse drift-line sampling as set with the "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" option of the "-> &DRIFT -> INTEGRATION-PARAMETERS" command. The only disadvantage of this over the alternative "-> &SIGNAL -> SIGNAL-PARAMETERS -> SAMPLE-WEIGHTING-FIELD", is that the calculation time is larger. [Default is 6-point Gaussian integration.] 3 SAMPLE-WEIGHTING-FIELD Only used with "-> &DRIFT -> methods -> microscopic" drift-line integration. Requests mid-point sampling of the weighting field over a drift-path segment when computing the induced current. [Default is 6-point Gaussian integration.] 2 THRESHOLD This instruction is withdrawn, use the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" instruction from the drift section instead. 2 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 "-> &DRIFT -> TRACK" Examples: !W
  track 0 1 2 0 2 4 exp
  track 0 1 2 0 2 4 muon energy 10 GeV
!W
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. Enters the size and granularity of time window in which you want to study the signals. 2 WINDOW By default, signals start at t=0 and are sampled every 0.01\ \μsec. The number of samples is by default MXLIST, usually 200 or 1000 depending on the compilation flags that were selected. The WINDOW command resets the signals to zero. The "-> &SIGNAL -> SIGNAL -> ADD" option of the "-> &SIGNAL -> SIGNAL" command can not be used on the first signal that is computed after a WINDOW command. The time window is reset when entering the &SIGNAL section. Each signal section must therefore contain, at its start, a WINDOWS statement. Format: !W
  WINDOW t_start t_step  [n_step]
!W
Example: !W
  window 0.5 0.01 200
!W
(This is a proper setting if your signals never start before 0.5\ \μsec and decay almost fully before 0.5+200\×0.01=2.5\ \μsec.) 2 WRITE-SIGNALS Writes the current set of signals to a dataset for further processing !D1 with programs like Spice (see http://wwwinfo.cern.ch/ce/ae/Pspice/). !Wwith programs like Spice. Writing is done when the command is executed, not while the "-> &SIGNAL -> SIGNAL" command runs as in versions of Garfield prior to 5.20. Format: !W
  WRITE-SIGNALS [FILE-NAME "-> &SIGNAL -> WRITE-SIGNALS -> file" ["-> &SIGNAL -> WRITE-SIGNALS -> member"]] [REMARK "-> &SIGNAL -> WRITE-SIGNALS -> remark"] ...
                ["-> &SIGNAL -> WRITE-SIGNALS -> FORMAT" {SPICE | SCEPTRE | SORIN}] ...
                [WRITE-IF "-> &SIGNAL -> WRITE-SIGNALS -> condition"] ...
                [UNITS "-> &SIGNAL -> WRITE-SIGNALS -> units"]
!W
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: !W
  wr-sig '/home/garfield/signal.dat'
!W
3 FORMAT By default, the signals are written in a Spice readable format as a Piece Wise Linear (PWL) input signal. One alternative is the Sceptre format, i.e. a comma between time and current but neither a heading nor a closing line. In the above 2 cases, the file contains records indicating the wires on which the signal was induced and the number of records that have been written out. With the Sorin format, the files do not contain any header. Instead, to identify the signals, the global variables EVENT and GROUP can be used in the file name. Note the use of escaped curly brackets: !W
  For event From 1 To 5 Do
     // Compute signals
     ...
     // Write to a file for off-line processing
     write-signals file="sorin_\\{event\\}_\\{group\\}.sig" ...
        units ampere second ...
        format sorin
  Enddo
!W
The EVENT variable is expected to be set by the user, the GROUP variable is automatically set to the number of the read-out group. In this format, the direct and cross-induced signals are added - they are not written to separate files. Other formats can be added - please contact the author. 3 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: !Wtable_start !T+P + . ------------------------------------------------------------ Variable Meaning ------------------------------------------------------------ SAMPLE the sample number, 1 to MXLIST SIGNAL in case of a pure signal, the current in \μA TIME the time corresponding to the sample in \μsec ------------------------------------------------------------ !Wtable_end The condition must evaluate to a "-> algebra -> variables -> types -> Logical". The condition is remembered, and re-used, by default from one call to the next - the initial default is 'True'. Examples: !W
  write-signal dataset "signal.list" wr-if 'time>0.5&time<1'

  write-signal dataset "signal.list" wr-if 'signal<-0.02'

  Call "-> 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
!W
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\ \μA. 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. 3 file The name of the "-> dataset -> structure -> file" in which you wish to write the signals. This argument may also be prefixed with the keyword DATASET for backwards compatibility. 3 member The name by which you will want to reference the "-> dataset -> structure -> member". 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. By default, the remark field will contain the read-out electrode number and an indication whether the signal is direct or cross induced, 3 units By default, the time is written to the dataset in units of \μsec and the current in \μA. You can change this via the UNITS keyword followed by the units that you prefer: !Wtable_start !T+P + +P R . --------------------------------------------------------------------------- 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 ----------------------------------------------------------------------------- !Wtable_end Some commonly abbreviations of these units are recognised (e.g. nsec). 2 WRITE-TRACK Writes the prepared track to a dataset. Format: See the "-> &DRIFT -> WRITE-TRACK" command in the drift section. 1 &STOP Terminates program execution decently. &EXIT and &QUIT are synonymous. &STOP has an advantage over an end-of-file condition in that &STOP closes the current section before ending program execution. This does not happen with end-of-file. Data that is output when the section is closed, such as gas files and gas plots, are therefore lost when end-of-file is used instead of &STOP. A section can be closed without stopping Garfield by means of the "-> &MAIN" command. Program execution can also terminate because errors are encountered while the "-> OPTIONS -> ON-ERROR-TERMINATE" option is in effect. Such termination is equivalent to issuing a &STOP command. 1 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. !D2 Some options can also be set from the command line, see http://cern.ch/garfield/command/command.html !WSome options can also be set from the !Wcommand line. Format: !W
  OPTIONS [NODEBUG | "-> OPTIONS -> DEBUG"] ...
          [NOIDENTIFY | "-> OPTIONS -> IDENTIFICATION"] ...
          [NOINPUT-LISTING | "-> OPTIONS -> INPUT-LISTING"] ...
          ["-> OPTIONS -> RECORDING" | NORECORDING] ...
          ["-> OPTIONS -> PROGRESS-PRINT" | NOPROGRESS-PRINT] ...
          ["-> OPTIONS -> ON-ERROR-CONTINUE" | "-> OPTIONS -> ON-ERROR-SKIP" | "-> OPTIONS -> ON-ERROR-TERMINATE"] ...
          [NODUMP-ON-GRAPHICS-ERROR | "-> OPTIONS -> DUMP-ON-GRAPHICS-ERROR"] ...
          ["-> OPTIONS -> WARN-BUT-WRITE" | "-> OPTIONS -> WARN-AND-NOWRITE" | "-> OPTIONS -> DELETE-OLD-MEMBER" ]
!W
Example: !W
  opt id
!W
Note: Actions depending on the setting of the ON-ERROR-... options are only gradually being introduced. 2 DEBUG Switches on debugging mode. Make sure you have a program listing at hand ! This may vastly increase the amount of output being produced. !D1 This option can be set from the command line on most systems. !WThis option can be set from the !Wcommand line !Won most systems. [Initially off by default.] 2 IDENTIFICATION Prints the names of a few selected subroutines when they are called. !D1 This option can be set from the command line on most systems. !WThis option can be set from the !Wcommand line !Won most systems. [Initially off by default.] 2 INPUT-LISTING Echos input lines to output. !D1 This option can be set from the command line on most systems. !WThis option can be set from the !Wcommand line !Won most systems. [This option is initially on by default in batch and initially off in interactive mode.] 2 RECORDING Requests recording all terminal input in a file, called GARFLAST.DAT, GARFLAST INPUT or garflast.dat depending on the operating system. !D1 This option can be set from the command line on most systems. !WThis option can be set from the !Wcommand line !Won most systems. [This option is initially off by default in batch and initially on in interactive mode.] 2 PROGRESS-PRINT Switching this option on, enables you to follow the progress of a few CPU intensive instructions (such as ARRIVAL and TIMING). !D1 This option can be set from the command line on most systems. !WThis option can be set from the !Wcommand line !Won most systems. [This option is initially off by default in batch and initially on in interactive mode.] 2 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.] 2 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 usable - 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.] 2 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.] 2 DUMP-ON-GRAPHICS-ERROR Produces a dump when encountering certain errors while projecting planes and removing hidden parts. Program execution is terminated after the dump has been created. This is a debugging option. [This option is switched off initially.] 3 PLASPL The dump for PLASPL is written to a file called "plaspl.dat" and contains the following pieces of information: !Wul_start - Line 1: The tolerances EPSGX, EPSGY, EPSGZ + their set flag - Line 2: Parameters (a,b,c,d) and colour index of plane 1 - Line 3: The number of points on curve 1, N1 - Lines 4 to N1+3: The coordinates of the points on curve 1 - Line N1+4: Parameters (a,b,c,d) and colour index of plane 2 - Line N1+5: The number of points on curve 2, N2 - Lines N1+6 to N1+N2+5: The coordinates of the points on curve 2 !Wul_end 3 GRAREA The dump for GRAREA is written to a file called "grarea.dat" and contains the following pieces of information: !Wul_start - Line 1: The tolerances EPSGX, EPSGY, EPSGZ + their set flag - Line 2: Frame dimensions (xmin, ymin, xmax, ymax) - Line 3: The number of points on the curve - Lines 4 to N+3: The (x,y) coordinates of the points !Wul_end 3 BUTFLY The dumps for BUTFLY and BUTFLD are written to files called "butfly.dat" and "butfld.dat". These files are written after elimination of multiply occurring points. The files contain the following pieces of information: !Wul_start - Line 1: The tolerances EPSGX, EPSGY, EPSGZ + their set flag - Line 2: The number of points on the curve - Lines 3 to N+2: The coordinates of the points !Wul_end 2 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.] 2 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 "-> OPTIONS -> ON-ERROR-SKIP" option is active. Program execution will be terminated if "-> OPTIONS -> ON-ERROR-TERMINATE" has been selected. [WARN-BUT-WRITE is default.] 2 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 "-> dataset -> RECOVER" dataset command. They can be removed from the file with the "-> dataset -> 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.] 1 Call !W
Do not use curly brackets in Call statements. !W
Call gives access to a wide variety of routines and data inside Garfield. Although originally intended as a debugging aid, procedure calls are now widely used whenever the commands do not provide sufficient flexibility. Input arguments can be "-> Global" variables, constants or expressions in terms of global variables and/or constants. Output variables are simple global variables - not constants nor expressions. An output variables which does not exist at the time of the procedure call, will be declared automatically. An existing global variable will be overwritten by the procedure. Procedure arguments which are used as input, must have (one of) the "-> algebra -> variables -> types" shown in the description. Some procedures can accept arguments of several types. Fits, for instance, can usually be done on matrices and on histograms. The descriptions of such procedures show two or more formats - one of which must be chosen, the formats should not be mixed. To ensure that the procedures that rely on cell and gas data work, one should call them only after the cell and gas sections have been left (e.g. via "-> &MAIN") - it is not enough to have entered the cell and gas data, cell and gas data become available to the procedures only when the sections have been left. Format: !W
  CALL procedure(arg1, arg2, ... )
!W
Examples are given in the descriptions of most procedures. 2 overview !Wul_start - service calls - numeric procedures - cell related procedures - gas related procedures - electric field calculation - drift-line related procedures - signal related procedures - histogramming - matrix manipulation - fitting procedures - character string manipulation - graphics !Wul_end Service calls: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 LIST_OBJECTS Lists the current booking state of objects PRINT Prints its arguments SLEEP Pause for a number of seconds TIME_LOGGING Enters a timing record ---------------------------------------------------------------------- !Wtable_end Numeric procedures: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 RND_IONISATION_ENERGY Generates an ionisation energy for 1 electron RND_VAVILOV Generates Vavilov-distributed random numbers RND_VAVILOV_FAST Generates Vavilov-distributed random numbers VAVILOV Computes Vavilov probabilities ZEROES Searches for zeroes of a function ---------------------------------------------------------------------- !Wtable_end Cell related procedures: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 GET_SOLID_DATA Returns information on a solid ---------------------------------------------------------------------- !Wtable_end Gas related procedures: !Wtable_start !T+IP + . --------------------------------------------------------------------------- Procedure name Purpose --------------------------------------------------------------------------- ATTACHMENT Returns the attachment coeff. for a given (E,B) CROSS_SECTION_IDENTIFIER Identifies a Magboltz cross section term. DIFFUSION_TENSOR Returns the diffusion tensor for a given (E,B) DRIFT_DIVERGENCE Returns the local divergence of the drift field. DRIFT_ROTATION Returns the drift field rotation matrices. DRIFT_VELOCITY Returns the drift velocity for a given (E,B) EXCITATION_IDENTIFIER Returns the identification string of a state. 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 IONISATION_IDENTIFIER Returns the identification string of a state. ION_MOBILITY Returns the ion mobility for a given (E,B) LEVEL_COUNT Returns the number of excitations and ionisations. LONGITUDINAL_DIFFUSION Returns sigma_L for a given (E,B) LORENTZ_ANGLE Returns the Lorentz angle for a given (E,B) TOWNSEND Returns the Townsend coeff. for a given (E,B) TRANSVERSE_DIFFUSION Returns sigma_T for a given (E,B) VELOCITY_BTRANSVERSE Returns the drift velocity component || Btrans VELOCITY_E Returns the drift velocity component || E VELOCITY_ExB Returns the drift velocity component || E\×B --------------------------------------------------------------------------- !Wtable_end Electric field calculation: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 ---------------------------------------------------------------------- !Wtable_end Drift-line related procedures: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 negative 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 Re-initialises 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 PRINT_DRIFT_LINE Prints the current drift-line RND_MULTIPLICATION Simulates multiplication over a drift-line ---------------------------------------------------------------------- !Wtable_end Signal related procedures: !Wtable_start !T+IP + . ---------------------------------------------------------------------- Procedure name Purpose ---------------------------------------------------------------------- ADD_SIGNALS Computes signals for the current drift-line 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 ---------------------------------------------------------------------- !Wtable_end Histogramming: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 one or more histograms 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 SKIP_HISTOGRAM Skips one or more histogram representations 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 ---------------------------------------------------------------------- !Wtable_end Matrix manipulation: !Wtable_start !T+IP + . ---------------------------------------------------------------------- Procedure name Purpose ---------------------------------------------------------------------- ADJUST_MATRIX Modifies on or more dimensions of a matrix BOOK_MATRIX Creates a new matrix DELETE_MATRIX Deletes one or more matrices 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 LOCATE_MAXIMUM Returns the indices of the maximum of a matrix LOCATE_MINIMUM Returns the indices of the minimum of a matrix MULTIPLY_MATRICES Multiplies 2 matrices PRINT_MATRIX Prints a matrix RESHAPE_MATRIX Changes the format of a matrix SOLVE_EQUATION Solves a matrix equation SORT_MATRIX Sorts a matrix STORE_SUBMATRIX Stores a sub-matrix in a matrix (internal) WRITE_MATRIX Writes a matrix to a file ---------------------------------------------------------------------- !Wtable_end Fitting: !Wtable_start !T+IP + . ---------------------------------------------------------------------- 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 ---------------------------------------------------------------------- !Wtable_end String manipulation: !Wtable_start !T+IP + . ---------------------------------------------------------------------- Procedure name Purpose ---------------------------------------------------------------------- DELETE_STRING Deletes one or more strings LIST_STRINGS Lists the currently known strings 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_REPLACE Replaces parts of a 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 ---------------------------------------------------------------------- !Wtable_end Graphics: !Wtable_start !T+IP + . ---------------------------------------------------------------------------- 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_BARCHART Plots a bar chart 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_MARKERS Plots a series of markers PLOT_OBLIQUE_ERROR_BAR Plots a series of oblique error bars PLOT_START Starts a plot PLOT_SURFACE Plots a 2-matrix as a 3D surface plot PLOT_TEXT Plots a text string PLOT_TITLE Plots a string in the title area PLOT_X_LABEL Plots a string in the x-label area PLOT_Y_LABEL Plots a string in the y-label area 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 ---------------------------------------------------------------------------- !Wtable_end 2 ADD_SIGNALS Computes signals for the current drift-line and adds them to the currently stored signals, if any. This call should be issued from the signal section and it should be preceded by: !Wul_start - a call to a procedure such as "-> Call -> DRIFT_ELECTRON", "-> Call -> DRIFT_MC_ELECTRON" or "-> Call -> DRIFT_ION" to establish a drift-line; - a "-> &SIGNAL -> SELECT" statement to list the electrodes you wish to read out. - optionally a "-> &SIGNAL -> SIGNAL-PARAMETERS" statement to establish suitable signal interpolation and weighting field integration parameters; - a "-> &SIGNAL -> WINDOW" statement to set the sampling interval; !Wul_end A "-> &SIGNAL -> RESET" "-> &SIGNAL -> RESET -> SIGNALS" command should be issued prior to the procedure call if you do not wish to add the new signals to signals computed earlier. Use "-> Call -> INDUCED_CHARGE" instead of ADD_SIGNALS if you wish to compute the charge induced in the various electrodes. Format: !W
  CALL ADD_SIGNALS(["-> Call -> ADD_SIGNALS -> shift" [,"-> Call -> ADD_SIGNALS -> weight" [,"-> Call -> ADD_SIGNALS -> options"]]])
!W
Example: !W
  "-> &SIGNAL"
  "-> &SIGNAL -> area" -1 -1 1 1
  "-> &SIGNAL -> select" s
  "-> &SIGNAL -> resolution" 0 0.001
  Call "-> Call -> drift_ion"(0, 0.001001)
  Call add_signals
  Call "-> Call -> get_signal"(1,time,direct,cross)
  "-> Global" qe 1.60217733E-19
  "-> Say" "Summed signal: {"-> algebra -> functions -> sum"(cross)*0.001*1e-12/qe}"
  Call "-> Call -> induced_charge"(0, 0.001001, 0, `ion`, 1, 0, 1, q)
  Say "Induced charge: {q}"
!W
After setting the time window and selecting the read-out electrode, we compute an ion drift-line from a point near a wire, located at (0,0). We then use the ADD_SIGNALS procedure to compute the signals induced by this ion and compare the integral of the current with the more accurate estimate from INDUCED_CHARGE over the same time window [0,1]\ \μsec. 3 shift Consider the usual signal induction process. An ionisation electron is deposited somewhere, it drifts towards an anode where it multiplies. Currents are induced both by the incoming electron and by the outgoing ions. The electron signal naturally starts at the time it starts to drift. The signal will initially be small, but it will become larger as the avalanche grows. This part is easy to simulate: you drift an electron using one of the procedures designed for this and use ADD_SIGNALS to compute the currents that are induced in the electrodes. There is a subtlety when it comes to the ions: the signals induced by the ions should not start at the time they start to drift, but at the time the electron started to drift. To account for this delay, you specify the electron drift time as first argument of the ADD_SIGNALS procedure. [By default, this delay is set to 0.] 3 weight This optional argument takes care of the case where more than one particle follows the same drift path. The signals are multiplied by the weight and only then added. [By default, the signals are given a weight of 1.] 3 options A "-> algebra -> variables -> types -> String" which can contain one or more of the following options: !Wtable_start !T+P + + . ------------------------------------------------------------------- Option Meaning Default ------------------------------------------------------------------- CROSS-INDUCED Requests cross induced signals Is default DIRECT Only direct signals are computed Not default ------------------------------------------------------------------- !Wtable_end The options have the same effect as the "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED" option of the "-> &SIGNAL -> SIGNAL" command. 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 "-> Call -> 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 "-> Call -> ADJUST_MATRIX -> pad". The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the matrix is successfully adjusted, and to False in case of a problem. Format: !W
  CALL ADJUST_MATRIX("-> Call -> ADJUST_MATRIX -> matrix", "-> Call -> ADJUST_MATRIX -> size"_1, size_2, ... size_n, "-> Call -> ADJUST_MATRIX -> pad")
!W
Examples: !W
  "-> Global" n=3
  Call "-> Call -> book_matrix"(a,2,n)
  For i From 1 To 2 Do
     Say "How many elements do you need 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 "-> Call -> print_matrix"(a)
!W
A matrix is initially booked as 2\×3, 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. !W
  Global a="-> algebra -> functions -> row"(1)
  Call adjust_matrix(a,1000,1)
!W
A trick to create a vector which contains everywhere the value 1, an alternative to using the "-> algebra -> functions -> ONES" function. 3 matrix The "-> algebra -> variables -> types -> 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.] 3 size A set of "-> algebra -> variables -> types -> Number"s, 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.] 3 pad A "-> algebra -> variables -> types -> 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.] 2 ATTACHMENT Returns the attachment coefficient, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. If the magnetic field is omitted, then all 3\ components are assumed to be zero, irrespective of the magnetic field settings that may be in effect. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The attachment coefficient is returned in 1/cm. Formats: !W
  CALL ATTACHMENT(e, attachment)
  CALL ATTACHMENT(ex, ey, ez, attachment)
  CALL ATTACHMENT(ex, ey, ez, bx, by, bz, attachment)
!W
2 AVALANCHE Simulates an electron induced avalanche, taking diffusion, multiplication and attachment into account. Use "-> Call -> AVALANCHE_SIGNAL" if you wish to compute induced currents. A simplified version of this procedure, which neglects the spatial development of the avalanche, is available as "-> Call -> RND_MULTIPLICATION". A more detailed version, which uses microscopic tracking, is available as "-> Call -> MICROSCOPIC_AVALANCHE". This procedure can produce 3\ kinds of output: !Wul_start - a graphical representation of the avalanche, - statistical information on the creation and absorption points of electrons and ions, - summary statistical information in the form of the final number of electrons and ions. !Wul_end The procedure first drifts an initial electron from the specified starting point. At each step, a number of secondary electrons and ions is drawn according to the local Townsend and attachment coefficients and the newly produced electrons are traced like the initial electron. Ion drift-lines are computed only if needed, i.e. when their start or end point has to be histogrammed, and when their path has to be plotted. Drifting of both electrons and ions is performed using the "-> &DRIFT -> methods -> Monte_Carlo" technique. Care has to be taken therefore that the "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" is set properly. The use of the "-> &DRIFT -> INTEGRATION-PARAMETERS -> PROJECTED-PATH-INTEGRATION" integration parameter is recommended in order to avoid a dependence of the multiplication on the step size. Format: !W
  CALL AVALANCHE("-> Call -> AVALANCHE -> x", "-> Call -> AVALANCHE -> y", "-> Call -> AVALANCHE -> z", "-> Call -> AVALANCHE -> options", "-> Call -> AVALANCHE -> n_electron", "-> Call -> AVALANCHE -> n_ion", ...
     "-> Call -> AVALANCHE -> formula"_1, "-> Call -> AVALANCHE -> histogram"_1, formula_2, histogram_2 ...)
!W
Example: !W
  "-> &DRIFT"
  "-> &DRIFT -> area" -0.02 -0.02 0.02 0.02
  "-> &DRIFT -> integration-parameters" m-c-dist-int 0.0002
  Call "-> Call -> book_histogram"(elec,50,0,2500)
  Call "-> Call -> book_histogram"(ion,50,0,2500)
  Call "-> Call -> book_histogram"(created,50,-0.02,+0.02)
  Call "-> Call -> book_histogram"(lost,50,-0.02,+0.02)
  Call "-> Call -> book_histogram"(end_e,50,-0.02,+0.02)
  Call "-> Call -> book_histogram"(end_ion,50,-0.02,+0.02)
  For i From 1 To 100 Do
     Call "-> 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 "-> Call -> fill_histogram"(elec,ne)
     Call "-> Call -> fill_histogram"(ion,ni)
     Call "-> Call -> plot_end"
  Enddo
  Call "-> Call -> fit_exponential"(elec,a,b,ea,eb,`plot`)
  Say "Slope: {-1/b}"
  !"-> graphics -> options" log-y
  Call "-> Call -> plot_histogram"(elec,`Electrons`,`Number of electrons after avalanche`)
  Call "-> 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
!W
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. 3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 options A "-> algebra -> variables -> types -> String" that can contain one or more of the following options: !Wtable_start !T+P + + . ------------------------------------------------------------------- Option Meaning Default ------------------------------------------------------------------- ABORT-100 Kills an avalanche at size 100 No ABORT-1000 Kills an avalanche at size 1000 No ABORT-10000 Kills an avalanche at size 10000 No ATTACHMENT Include attachment If data present NOATTACHMENT Don't include attachment If data absent NOPLOT-ELECTRON Don't plot electron drift-lines Yes NOPLOT-ION Don't plot ion drift-lines Yes NOTOWNSEND Don't include multiplication If data absent PLOT-ELECTRON Plot electron drift-lines No PLOT-ION Plot ion drift-lines No TOWNSEND Include multiplication If data present ------------------------------------------------------------------- !Wtable_end 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 "-> Call -> PLOT_DRIFT_AREA") has to be opened before the call to AVALANCHE if you wish to use the PLOT-ELECTRON or PLOT-ION options. 3 n_electron Contains on return the "-> algebra -> variables -> types -> Number" of electrons produced in the avalanche minus the number of electrons lost via attachment. This is an optional output parameter. If present, it must be modifiable. The value assigned to this parameter on entry is not used and will be lost after the call. 3 n_ion Contains on return the "-> algebra -> variables -> types -> Number" of ions produced in the avalanche. This is an optional output parameter. If present, it must be modifiable. The value assigned to this parameter on entry is not used and will be lost after the call. 3 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: !Wul_start * Information about the location where electron-ion pairs are produced: X_CREATED (or R_CREATED), Y_CREATED (or PHI_CREATED), Z_CREATED, T_CREATED. * Information about the location where electrons are lost through attachment: X_LOST (or R_LOST), Y_LOST (or PHI_LOST), Z_LOST, T_LOST. * Information about the point where electrons end up if they are not lost through attachment: X_E (or R_E), Y_E (or PHI_E), Z_E, T_E. * Information about the point where ions end up X_ION (or R_ION), Y_ION (or PHI_ION), Z_ION, T_ION. !Wul_end 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. The "value" part should evaluate to a "-> algebra -> variables -> types -> Number" while "condition" should be a "-> algebra -> variables -> types -> Logical". This argument should be provided in the form of a "-> algebra -> variables -> types -> String". The string is not modified in the call. 3 histogram A reference to the "-> algebra -> variables -> types -> Histogram"s 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. 2 AVALANCHE_INFORMATION Returns information about the electron trajectories in an avalanche previously computed using "-> Call -> AVALANCHE", "-> Call -> AVALANCHE_SIGNAL" or "-> Call -> MICROSCOPIC_AVALANCHE". This procedure can be used to add e.g. ion-induced currents to a signal, as is illustrated with an example for the "-> Call -> AVALANCHE_SIGNAL" procedure. Format: !W
  CALL AVALANCHE_INFORMATION(item1, [index1,] value1, item2, [index2,], value2 ...)
!W
3 item A "-> algebra -> variables -> types -> String" with one of the values from the table below. Some items require an index as following argument. !Wtable_start !T+ + + . ------------------------------------------------------------------------- item index value ------------------------------------------------------------------------- ELECTRONS - Number of electrons in the avalanche X-START electron number x-Coordinate of the production point Y-START electron number y-Coordinate of the production point Z-START electron number z-Coordinate of the production point T-START electron number Production time X-END electron number x-Coordinate of the end of the trajectory Y-END electron number y-Coordinate of the end of the trajectory Z-END electron number z-Coordinate of the end of the trajectory STATUS-CODE electron number Numeric status of the electron drift-line STATUS-STRING electron number Status string of the electron drift-line T-END electron number Time at which the electron ends ------------------------------------------------------------------------- !Wtable_end STATUS-STRING and STATUS-CODE return the same "-> &DRIFT -> methods -> status" information in a different form. While the "-> algebra -> variables -> types -> String" provided by STATUS-STRING is convenient for printing, the "-> algebra -> variables -> types -> Number" given by STATUS-CODE is better suited for use in scripts. 3 index The electron about which you wish to obtain information. See "-> Call -> AVALANCHE_INFORMATION -> item". 3 value Should be a modifiable argument. Contains on successful return the desired information. 2 AVALANCHE_SIGNAL Offers all the functionality of "-> Call -> AVALANCHE", and calculates in addition the signals induced in the various electrodes. The procedure first drifts an initial electron from the specified starting point. The currents induced by the electron are added to the signals if requested. At each step, a number of secondary electrons and ions is drawn according to the local Townsend and attachment coefficients. Trajectories, signals and secondaries are computed for the newly produced electrons as for the initial electron. Start and end points of all electrons can be histogrammed. Ion drift-lines are computed if needed, i.e. when ion induced currents have been requested, when their start or end point has to be histogrammed, and when their path has to be plotted. Ions do not generate secondaries in this procedure. This call should be issued from the signal section and it should be preceded by: !Wul_start - an "-> &SIGNAL -> AREA" statement to indicate the region in which electrons and ions are allowed to move; - a "-> &SIGNAL -> WINDOW" statement to set the sampling interval; - a "-> &SIGNAL -> SELECT" statement to list the electrodes you wish to read out. !Wul_end Drifting of both electrons and ions is performed using the "-> &DRIFT -> methods -> Monte_Carlo" technique. Care has to be taken therefore that the "-> &DRIFT -> INTEGRATION-PARAMETERS -> step_size" is set properly. The use of the "-> &DRIFT -> INTEGRATION-PARAMETERS -> PROJECTED-PATH-INTEGRATION" integration parameter is recommended in order to avoid a dependence of the multiplication on the step size. Ion tail calculation requires the possibility of drifting ions from the vicinity of electrodes. To enable this, one may have to switch "-> &DRIFT -> INTEGRATION-PARAMETERS -> CHECK-ALL-WIRES" off. If electron induced currents are to be computed in chambers with wires, then you have to reduce the "-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS" considerably. This procedure adds the newly computed signals to the signal banks. A "-> &SIGNAL -> RESET" "-> &SIGNAL -> RESET -> SIGNALS" command should therefore be issued prior to the procedure call if you wish to obtain only the newly computed signals. Format: !W
  CALL AVALANCHE_SIGNAL("-> Call -> AVALANCHE_SIGNAL -> x", "-> Call -> AVALANCHE_SIGNAL -> y", "-> Call -> AVALANCHE_SIGNAL -> z", "-> Call -> AVALANCHE_SIGNAL -> options", "-> Call -> AVALANCHE_SIGNAL -> n_electron", "-> Call -> AVALANCHE_SIGNAL -> n_ion", ...
     "-> Call -> AVALANCHE_SIGNAL -> formula"_1, "-> Call -> AVALANCHE_SIGNAL -> histogram"_1, formula_2, histogram_2 ...)
!W
Example 1: !W
  "-> &SIGNAL"
  "-> &SIGNAL -> area" -0.2 -0.2 0.2 0.2
  "-> &SIGNAL -> integration-parameters" max-step 0.01 int-acc 1e-10 m-c-dist-int 0.0002 projected ...
     trap-radius 1.01
  "-> &SIGNAL -> select" s
  "-> &SIGNAL -> window" 0 0.001
  Call "-> Call -> plot_drift_area"
  Call avalanche_signal(0.01,0.01,0,`plot-electron`,ne,ni)
  Call "-> Call -> plot_end"
  "-> &SIGNAL -> plot-signals"
!W
The integration parameters are set such that very small steps are taken, for higher accuracy. Also, the trap radius is made small to avoid avalanche truncation near the wire. Then. we use the AVALANCHE_SIGNAL procedure to generate an avalanche, which is plotted, and to compute the signal its electrons (but not its ions !) induces. To add the ion signals, one would use the AVALANCHE_INFORMATION and "-> Call -> DRIFT_ION_3" procedures, as illustrated below: !W
  Call "-> Call -> avalanche_information"(`electrons`,ne)
  For ie From 1 To ne Do
     Call "-> Call -> avalanche_information"( `x-start`, ie, xe, `y-start`, ie, ye, ...
        `z-start`, ie, ze, `t-start`, ie, te)
     Call "-> Call -> drift_ion_3"(xe, ye, ze, status, tion)
     Call "-> Call -> add_signals"(te)
  Enddo
!W
Example 2: !W
  "-> Global" sumaval=0
  Global sumdetail=0
  For i From 1 To 10 Do
     "-> &SIGNAL -> reset" signals
     Call avalanche_signal(0.01,0.01,0,`noplot-electron,ion-tail`,ne,ni)
     Say "Avalanche {i}, electrons/ions: {ne}/{ni}"
     Call "-> Call -> get_signal"(1,time,direct,cross)
     Global sumaval=sumaval+cross
     reset signals
     "-> &SIGNAL -> signal" detailed-ion-tail cross-induced mc-drift
     Call "-> Call -> get_signal"(1,time,direct,cross)
     Global sumdetail=sumdetail+direct
  Enddo

  Global sumaval=sumaval/"-> algebra -> functions -> sum"(sumaval)
  Global sumdetail=sumdetail/sum(sumdetail)
  Call "-> Call -> plot_graph"(time,sumaval,`Time [microsec]`,`Signal`, ...
     `Comparison`)
  Call "-> Call -> plot_line"(time,sumdetail,`function-2`)
  Call "-> Call -> plot_end"
!W
This example demonstrates a comparison with the "-> &SIGNAL -> SIGNAL -> DETAILED-ION-TAIL" method of calculating a signal. 3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 options A "-> algebra -> variables -> types -> String" that can contain one or more of the following options: !Wtable_start !T+P + + . ------------------------------------------------------------------- Option Meaning Default ------------------------------------------------------------------- ABORT-100 Kills an avalanche at size 100 No ABORT-1000 Kills an avalanche at size 1000 No ABORT-10000 Kills an avalanche at size 10000 No ATTACHMENT Include attachment If data present CROSS-INDUCED Requests cross induced signals Yes DIRECT Computes only direct signals No ELECTRON-PULSE Add signals due to electrons No NOATTACHMENT Don't include attachment If data absent NOELECTRON-PULSE Do not compute electron signals Yes NOPLOT-ELECTRON Don't plot electron drift-lines Yes NOPLOT-ION Don't plot ion drift-lines Yes NOTOWNSEND Don't include multiplication If data absent PLOT-ELECTRON Plot electron drift-lines No PLOT-ION Plot ion drift-lines No TOWNSEND Include multiplication If data present ------------------------------------------------------------------- !Wtable_end The TOWNSEND and ATTACHMENT options can only be selected if the corresponding data has been entered in the gas section. See the "-> &SIGNAL -> SIGNAL -> CROSS-INDUCED" option of the "-> &SIGNAL -> SIGNAL" command for the distinction between direct and cross induced signals. A plot frame (e.g. with "-> Call -> PLOT_DRIFT_AREA") has to be opened before the call to AVALANCHE_SIGNAL if you wish to use the PLOT-ELECTRON or PLOT-ION options. 3 n_electron See "-> Call -> AVALANCHE -> n_electron". 3 n_ion See "-> Call -> AVALANCHE -> n_ion". 3 formula See "-> Call -> AVALANCHE -> formula". 3 histogram See "-> Call -> AVALANCHE -> histogram". 2 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 "-> algebra -> variables -> predefined -> OK" will be set to False, otherwise to True. Format: !W
  CALL BARYCENTRE("-> Call -> BARYCENTRE -> histogram", "-> Call -> BARYCENTRE -> barycentre" [, "-> Call -> BARYCENTRE -> nbin"])
!W
3 histogram The "-> algebra -> variables -> types -> Histogram" of which the barycentre is to be computed. Histograms are normally linked to global variables, they can be created via "-> Call -> BOOK_HISTOGRAM", read from a file with "-> Call -> GET_HISTOGRAM", by operations between other existing histograms, or obtained from some commands with a KEEP-HISTOGRAM option. [No default] 3 barycentre On successful completion of the procedure, this variable, a "-> algebra -> variables -> types -> 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. 3 nbin An optional argument of type "-> algebra -> variables -> types -> Number" that specifies the window width used both for searching the peak and for computing the barycentre. [Default is 3] 2 BOOK_HISTOGRAM This procedure is the principal means of creating a new "-> algebra -> variables -> types -> Histogram". Histograms can be filled with "-> Call -> FILL_HISTOGRAM", plotted with "-> Call -> PLOT_HISTOGRAM", fitted with a variety of functions (e.g. "-> Call -> FIT_POLYA") and written to a file with "-> Call -> 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 "-> Call -> BOOK_HISTOGRAM -> options -> 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. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the histogram is successfully booked, and to False in case of a problem. Format: !W
  CALL BOOK_HISTOGRAM("-> Call -> BOOK_HISTOGRAM -> reference", [number of "-> Call -> BOOK_HISTOGRAM -> bins", ...
       ["-> Call -> BOOK_HISTOGRAM -> minimum", "-> Call -> BOOK_HISTOGRAM -> maximum"]] [, "-> Call -> BOOK_HISTOGRAM -> options"]])
!W
Example: !W
  Call book_histogram(ref,10,2,3)
  Call book_histogram(ref,10,`integer`)
!W
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 "-> Call -> FILL_HISTOGRAM". 3 reference Contains, on successful completion of the procedure, a reference to the histogram that has been created. This reference is a "-> Global" variable of type "-> algebra -> variables -> types -> Histogram" which is from then on be used when filling the histogram with "-> Call -> FILL_HISTOGRAM", and also when doing arithmetic with it. One can for instance add two histograms via a simple + operation between the references of the two histograms. This parameter should have the format of a normal variable name (e.g. A, REF, B_1) not of e.g. a constant number, string or logical. 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. Hence, when you issue a BOOK_HISTOGRAM call for an histogram which already exists, you effectively reset the histogram. This argument is mandatory. 3 bins Should contain on input the "-> algebra -> variables -> types -> Number" of bins in the histogram. The maximum number of bins is set at compilation time and equals MXLIST/2, where MXLIST is usually 1000. This argument is optional, default value is 100 bins. 3 minimum The minimum and maximum are "-> algebra -> variables -> types -> Number"s which respectively set the lower limit of the first bin and the upper limit of the last bin of the histogram. The "-> Call -> BOOK_HISTOGRAM -> options -> AUTOSCALE" option is implied if these arguments are omitted. The range is ignored if the autoscaling is explicitly requested as one of the "-> Call -> BOOK_HISTOGRAM -> options". If you specify the minimum, you must also specify the maximum. You can later modify the horizontal range of the histogram: "-> Call -> CUT_HISTOGRAM" will extract a piece of an histogram, and "-> Call -> HISTOGRAM_TO_MATRIX" combined with "-> Call -> MATRIX_TO_HISTOGRAM" permits multiplying the horizontal scale by a factor. 3 maximum See "-> Call -> BOOK_HISTOGRAM -> minimum". 3 options A character "-> algebra -> variables -> types -> String" that can contain the following options: !Wtable_start !T+PS + . ------------------------------------------------------------- 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 ------------------------------------------------------------- !Wtable_end 4 AUTOSCALE Requests automatic computation of the histogram range. When this option is in effect, a rough range is set to !W
       [mean - 3*RMS, mean + 3*RMS]
!W
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 "-> Call -> BOOK_HISTOGRAM -> options -> 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.] 4 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] 4 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.] 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.] 2 BOOK_MATRIX Creates a "-> algebra -> variables -> types -> Matrix" of specified dimensions. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the matrix is successfully created, and to False in case of a problem. Format: !W
  CALL BOOK_MATRIX("-> Call -> BOOK_MATRIX -> reference", "-> Call -> BOOK_MATRIX -> size"_1, size_2, ...)
!W
Example: !W
  Call book_matrix(cube,3,3,3)
!W
Books a 3\×3\×3 matrix which can be accessed via the global variable CUBE. 3 reference Contains, on successful completion of the procedure, a reference to the matrix that has been created. This reference is a "-> Global" variable of type "-> algebra -> variables -> types -> Matrix" which can from then on be used when doing arithmetic with the matrix. This argument should be a simple variable name, not an expression. It must also be modifiable, hence it can't be a constant. 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. This argument is mandatory. 3 size Should contain on input a dimension of the matrix. The number of these arguments is equal to the number of dimensions of the matrix. The number of dimensions is limited by a compilation parameter, usually set to 10. Each parameter of this kind should be of type "-> algebra -> variables -> types -> Number". One such argument is mandatory. These arguments are not modified by the procedure. 2 CARTESIAN_TO_INTERNAL Applies the conformal mapping of Cartesian (x,y) coordinates to internal (\ρ,\φ) coordinates. The (\ρ,\φ) coordinates are used internally in the program when the cell is described in polar coordinates. The internal coordinates are defined by: !W
  \ρ = 0.5*log(x\²+y\²)         [dimension not defined]
  \φ = arctan(y/x)            [\φ in radians]
!W
The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL CARTESIAN_TO_INTERNAL(x,y,\ρ,\φ)
!W
2 CARTESIAN_TO_POLAR Converts Cartesian (x,y) coordinates to polar (r,\φ) coordinates. The angle \φ is in degrees. The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL CARTESIAN_TO_POLAR(x,y,r,\φ)
!W
2 CONVOLUTE Computes the convolution of 2 "-> algebra -> variables -> types -> Histogram"s (hist1 and hist2) and stores the result (hist3) 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 "-> algebra -> variables -> predefined -> OK" will be set to False, otherwise to True. Format: !W
  CALL CONVOLUTE(hist1, hist2, hist3)
!W
2 CROSS_SECTION_IDENTIFIER Returns information about a Magboltz cross section. This procedure is used to identify the elements of the rate vector returned by "-> Call -> DRIFT_MICROSCOPIC_ELECTRON". Format: !W
  CALL CROSS_SECTION_IDENTIFIER("-> Call -> CROSS_SECTION_IDENTIFIER -> number", "-> Call -> CROSS_SECTION_IDENTIFIER -> identifier", "-> Call -> CROSS_SECTION_IDENTIFIER -> type")
!W
Example: listing only the ionisation cross sections and counting the total number of ionisations !W
  Call "-> Call -> drift_microscopic_electron"(x, y, z, status, time, ``, ...
     100.0, 4.0, 0,0,0, histe, vec)
  Global sum=0
  For i From 1 To "-> algebra -> functions -> size"(vec) Do
     Call cross_section_identifier(i, level, type)
     If type#`Ionisation` Then Iterate
     Say "Level {i} = {level}, count = {"-> algebra -> functions -> number"(vec[i])}, type = {type}"
     Global sum=sum+"-> algebra -> functions -> number"(vec[i])
  Enddo
  Say "Total number of ionisations: {sum}"
!W
3 number Should on input contain the Magboltz cross section "-> algebra -> variables -> types -> Number", i.e. the index in the "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> rates" vector returned by the "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure. Use the "-> algebra -> functions -> SIZE" function to find the length of the rates vector. [Mandatory argument, no default.] 3 identifier Contains on return a "-> algebra -> variables -> types -> String" which provides information about the cross section term. Usually, the first 15 characters contain the Magboltz name of the gas while the last 45 characters are the Magboltz cross section description. Any contents of this argument on input will be lost after the call. [Mandatory argument.] 3 type Contains on successful return one of the following "-> algebra -> variables -> types -> String"s: !Wdl_start !T+ + ----------------------------------------------------------------------------------- String Description ----------------------------------------------------------------------------------- Attachment Attachment, usually one such cross section per molecule Elastic Elastic scattering cross section, usually one per molecule Excitation Scattering with energy loss producing an excited state Inelastic Scattering with energy loss, but not leading to an excitation Ionisation Ionisation, usually one per molecule Super-elastic Scattering in which the electron gains energy ----------------------------------------------------------------------------------- !Wdl_end [This argument is optional.] 2 CUMULATE_HISTOGRAM Creates the cumulative version of an existing "-> algebra -> variables -> types -> Histogram". This procedure may be called while filling is in progress, but should not be called for "-> Call -> BOOK_HISTOGRAM -> options -> AUTOSCALE" histograms before the range has been established. The input histogram is not modified by a call to this procedure. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the operation was successful and to False if it wasn't. Format: !W
  CALL CUMULATE_HISTOGRAM(refin, refout)
!W
Example: !W
  "-> Vector" a
  1 2 3 2 1

  Call "-> Call -> matrix_to_histogram"(a,1,6,aa)

  Call "-> Call -> plot_histogram"(aa)
  Call "-> Call -> plot_end"

  Call cumulate_histogram(aa,bb)

  Call "-> Call -> plot_histogram"(bb)
  Call "-> Call -> plot_end"
!W
An histogram is created from a "-> Vector" and a call to "-> Call -> MATRIX_TO_HISTOGRAM". We then call CUMULATE_HISTOGRAM and verify the result with "-> Call -> PLOT_HISTOGRAM". 2 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 "-> Call -> REBIN_HISTOGRAM" for that purpose. This procedure may be called while filling is in progress, but should not be called for "-> Call -> BOOK_HISTOGRAM -> options -> 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 "-> algebra -> variables -> predefined -> OK" will be set to False, otherwise to True. Format: !W
  CALL CUT_HISTOGRAM("-> Call -> CUT_HISTOGRAM -> ref_in", "-> Call -> CUT_HISTOGRAM -> xmin", "-> Call -> CUT_HISTOGRAM -> xmax", "-> Call -> CUT_HISTOGRAM -> ref_out")
!W
Example: !W
  Call "-> Call -> book_histogram"(gauss,500,-50,50)
  For i From 1 To 500 Do
     Call "-> Call -> fill_histogram"(gauss,"-> algebra -> functions -> rnd_gauss")
  Enddo
  Call "-> Call -> plot_histogram"(gauss)
  Call "-> Call -> plot_end"

  Call cut_histogram(gauss,-5,5,new)
  Call "-> Call -> plot_histogram"(new)
  Call "-> Call -> plot_end"
!W
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. 3 ref_in The "-> algebra -> variables -> types -> Histogram" of which you wish to cut a part. This histogram is not modified by the procedure. [No default, this is a mandatory argument.] 3 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 "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument] 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 "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument] 3 ref_out On successful completion, this argument is set equal to an "-> algebra -> variables -> types -> 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. 2 DELETE_HISTOGRAM Deletes one or more "-> algebra -> variables -> types -> Histogram"s. All histograms, whether associated with a global variable or not, are deleted if arguments are omitted. The memory associated with the histograms is only released at the next histogram garbage collect, usually only carried out when there are no free histogram slots left. If the histograms were known via a "-> Global" variable, as is usually the case, then the global variables will exist after this call but their type will have changed to "-> algebra -> variables -> types -> Undefined". Format: !W
  CALL DELETE_HISTOGRAM("-> Call -> DELETE_HISTOGRAM -> reference"_1, reference_2, ...)
!W
3 reference The histogram is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM". 2 DELETE_MATRIX The DELETE_MATRIX procedure frees the memory occupied by one or more variables of type "-> algebra -> variables -> types -> Matrix" and returns the associated "-> Global" variables to type "-> algebra -> variables -> types -> 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. DELETE_MATRICES may be used as a synonym for DELETE_MATRIX. Format: !W
  CALL DELETE_MATRIX(matrix_1, matrix_2, ...)
!W
Example: !W
  Call "-> Call -> book_matrix"(a,2,3,4,5)
  Call delete_matrix(a)
  Call "-> Call -> list_matrices"
!W
2 DELETE_STRING Frees the memory occupied by one or more "-> algebra -> variables -> types -> String"s and returns the associated "-> Global" variables to type "-> algebra -> variables -> types -> Undefined". If called without arguments, then all global variables of type String are deleted, but strings not associated with a global variable are left in peace - strings are used also outside the context global variables. This procedure is almost never used since liberating string storage can also be achieved by assigning e.g. a number to global variables representing strings. Format: !W
  CALL DELETE_STRING(string_1, string_2, ...)
!W
Example: !W
  "-> Global" a=`test`
  Call delete_string(a)
  "-> Say" {a}
!W
2 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 as an option and which is by default quadratic. Format: !W
  CALL DERIVATIVE("-> Call -> DERIVATIVE -> x", "-> Call -> DERIVATIVE -> y", "-> Call -> DERIVATIVE -> x_int", "-> Call -> DERIVATIVE -> dy" [, "-> Call -> DERIVATIVE -> option"])
!W
Example: !W
  "-> 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}."
!W
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`. 3 x A 1-dimensional "-> algebra -> variables -> types -> Matrix" of ordinates. This array must be strictly in increasing order and must have the same length as "-> Call -> DERIVATIVE -> y". 3 y A 1-dimensional "-> algebra -> variables -> types -> Matrix" of function values. This array must have the same length as "-> Call -> DERIVATIVE -> x". 3 x_int A "-> algebra -> variables -> types -> Number", the value of "-> Call -> DERIVATIVE -> x" at which y'(x) is to be computed. 3 dy On return, a "-> algebra -> variables -> types -> Number" approximately equal to y'(x) 3 option A character "-> algebra -> variables -> types -> String" that can contain the following keywords: !Wtable_start !T+P + + . ------------------------------------------------------------- Keyword Meaning Notes ------------------------------------------------------------- LINEAR Linear interpolation Rarely useful PARABOLIC Quadratic interpolation Default CUBIC Cubic interpolation Risk of oscillation ------------------------------------------------------------- !Wtable_end 2 DIFFUSION_TENSOR Returns the diffusion tensor, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The tensor, contrary to the convention used for the diffusion coefficients, is returned in cm. The diagonal components correspond to \σ\E\\², \σ\Btrans\\² and \σ\E\×B\\² and while the off-diagonal elements are the covariances between the diffusion along (E, Btrans, E\×B). The tensor is a 3\×3 Matrix if all input arguments are Numbers, otherwise it will be an n\×3\×3 Matrix. Formats: !W
  CALL DIFFUSION_TENSOR(e, covariance)
  CALL DIFFUSION_TENSOR(ex, ey, ez, covariance)
  CALL DIFFUSION_TENSOR(ex, ey, ez, bx, by, bz, covariance)
!W
Example: !W
  "-> Call" diffusion_tensor(100,0,0,  0,0,100, cov)
  "-> Say" "Diffusion along E:         {10000*"-> algebra -> functions -> sqrt"(cov[1;1])} micron"
  Say "Diffusion along Btrans:    {10000*sqrt(cov[2;2])} micron"
  Say "Diffusion along ExB:       {10000*sqrt(cov[3;3])} micron"
  Say "Correlation E vs Btrans:   {100*cov[1;2]/sqrt(cov[1;1]*cov[2;2])} %"
  Say "Correlation E vs ExB:      {100*cov[1;3]/sqrt(cov[1;1]*cov[3;3])} %"
  Say "Correlation Btrans vs ExB: {100*cov[2;3]/sqrt(cov[2;2]*cov[3;3])} %"
!W
This example shows the interpretation of the components of the diffusion tensor. 2 DIMENSIONS Returns, for the "-> algebra -> variables -> types -> Matrix" that is given as first argument, the number of dimensions (n_dimensions) and a vector with the size of the matrix in each of the dimensions (dimension_vector). Use the "-> algebra -> functions -> SIZE" function if you only need to know the overall size of the matrix. Format: !W
  CALL DIMENSIONS(matrix, n_dimensions, dimension_vector)
!W
Example: !W
  Call "-> Call -> get_matrix"(abc,`abc.mat`)
  Call dimensions(abc,n_dim,dim_abc)
  For i From 1 To n_dim Do
     If i=1 Then
        Global shape="-> algebra -> functions -> string"("-> algebra -> functions -> number"(dim_abc[i]))
     Else
        Global shape=shape/` x `/"-> algebra -> functions -> string"("-> algebra -> functions -> number"(dim_abc[i]))
     Endif
  Enddo
  Say "Matrix abc has {n_dim} dimensions and its shape is {shape}."
!W
A matrix is read from a file, and the example shows how one can find out what the structure of the object is. The "-> algebra -> functions -> NUMBER" function is used to convert the 1-dimensional matrices dim_abc[i] into numbers - this is purely aesthetic: "-> Say" would place parentheses around the individual dimensions. 2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_ELECTRON("-> Call -> DRIFT_ELECTRON -> x", "-> Call -> DRIFT_ELECTRON -> y" [, "-> Call -> DRIFT_ELECTRON -> status" [, "-> Call -> DRIFT_ELECTRON -> time" [, "-> Call -> DRIFT_ELECTRON -> diffusion" ...
       [, "-> Call -> DRIFT_ELECTRON -> multiplication" [, "-> Call -> DRIFT_ELECTRON -> attachment"]]]]])
!W
3 x One of the "-> Call -> DRIFT_ELECTRON -> coordinates" of the starting point of the drift-line. 3 y One of the "-> Call -> DRIFT_ELECTRON -> coordinates" of the starting point of the drift-line. 3 z One of the "-> Call -> DRIFT_ELECTRON -> coordinates" of the starting point of the drift-line. 3 coordinates The starting point of the drift-line should be specified using the "-> &CELL -> methods -> coordinate_system" which is used for the chamber. The coordinates should be specified as constants, variables or expressions that are or evaluate to "-> algebra -> variables -> types -> Number"s. 3 status See "-> &DRIFT -> methods -> status". 3 time Contains, on successful completion, the total drift time. The time is expressed in \μsec. 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. 3 diffusion Contains, on successful completion, the "-> &DRIFT -> methods -> diffusion" integrated over the trajectory of the electron. The diffusion is expressed in \μsec. 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. This argument is optional. The diffusion is not integrated if the argument is omitted, you should therefore leave it out if you do not need the value. 3 multiplication Contains, on successful completion, the exponentiated integral of the Townsend coefficient over the drift path. This dimensionless "-> algebra -> variables -> types -> Number" is equal to the mean "-> &DRIFT -> methods -> multiplication", i.e. the mean number of secondary electrons produced along the trajectory of the electron that is being drifted, assuming exponential avalanche fluctuations and neglecting attachment. 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. This argument is optional. The multiplication is not computed if the argument is omitted, you should therefore leave it out if you do not need the value. 3 attachment Contains, on successful completion, the reciprocal of the exponentiated integral of the "-> &DRIFT -> methods -> attachment" coefficient over the drift path. This dimensionless "-> algebra -> variables -> types -> Number" is equal to the probability that the electron will survive "-> &DRIFT -> methods -> attachment" until the end point of its drift path, assuming there is no multiplication along the way. 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. This argument is optional. The attachment losses are not computed if the argument is omitted, you should therefore leave it out if you do not need the value. 2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_ELECTRON_3("-> Call -> DRIFT_ELECTRON_3 -> x", "-> Call -> DRIFT_ELECTRON_3 -> y", "-> Call -> DRIFT_ELECTRON_3 -> z" [, "-> Call -> DRIFT_ELECTRON_3 -> status" [, "-> Call -> DRIFT_ELECTRON_3 -> time" [, "-> Call -> DRIFT_ELECTRON_3 -> diffusion" ...
       [, "-> Call -> DRIFT_ELECTRON_3 -> multiplication" [, "-> Call -> DRIFT_ELECTRON_3 -> attachment"]]]]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 3 diffusion See "-> Call -> DRIFT_ELECTRON -> diffusion". 3 multiplication See "-> Call -> DRIFT_ELECTRON -> multiplication". 3 attachment See "-> Call -> DRIFT_ELECTRON -> attachment". 2 DRIFT_INFORMATION Returns various pieces of information about the current drift-line. This procedure can be called after any of the drift-line computation procedures has been called (e.g. "-> Call -> DRIFT_ELECTRON"). Format: !W
  CALL DRIFT_INFORMATION(             ...
       [ `CHARGE`, "-> Call -> DRIFT_INFORMATION -> q" ] ,              ...
       [ `DRIFT-TIME`, "-> Call -> DRIFT_INFORMATION -> time" ] ,       ...
       [ `ELECTRODE`, "-> Call -> DRIFT_INFORMATION -> electrode" ] ,   ...
       [ `PARTICLE`, "-> Call -> DRIFT_INFORMATION -> particle" ] ,     ...
       [ `PATH-LENGTH`, "-> Call -> DRIFT_INFORMATION -> path" ] ,      ...
       [ `STATUS-CODE`, "-> Call -> DRIFT_INFORMATION -> istat" ] ,     ...
       [ `STATUS-STRING`, "-> Call -> DRIFT_INFORMATION -> status" ] ,  ...
       [ `STEPS`, "-> Call -> DRIFT_INFORMATION -> nsteps" ] ,          ...
       [ `TECHNIQUE`, "-> Call -> DRIFT_INFORMATION -> technique" ] ,   ...
       [ `X-START`, "-> Call -> DRIFT_INFORMATION -> coordinate" ] ,    ...
       [ `Y-START`, coordinate ] ,    ...
       [ `Z-START`, coordinate ] ,    ...
       [ `X-END`, coordinate ] ,      ...
       [ `Y-END`, coordinate ] ,      ...
       [ `Z-END`, coordinate ])
!W
Example: !W
  Call "-> Call -> plot_drift_area"
  Call "-> Call -> drift_electron_3"(2.5,3.5,4.5,status,time)
  Call "-> Call -> plot_drift_line"
  Call "-> Call -> plot_end"
  "-> Say" "Status: {status}"
  Call "-> 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
!W
An electron drift-line is computed using the Runge Kutta method with "-> Call -> 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 "-> Call -> 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. 3 q Contains, on return, the charge of the last particle that has been drifted. The charge is expressed in multiples of the electron charge and will thus be -1 for electrons and +1 for positive ions. This argument must be modifiable. It will be of type "-> algebra -> variables -> types -> Number" after the call. Any value this argument may have before the procedure call is lost. 3 time Contains, on return, the total drift time in \μsec of the last drift-line that has been computed. This argument must be modifiable. It will be of type "-> algebra -> variables -> types -> Number" after the call. Any value this argument may have before the procedure call is lost. 3 electrode The read-out group "-> algebra -> variables -> types -> Number" of the electrode that was hit by the last drift-line. A value of 0 is assigned if the particle did not reach an electrode that is read out. Read-out group numbers are assigned by the "-> &FIELD -> SELECT" statement. This argument must be modifiable. Any value this argument may have before the procedure call is lost. 3 particle Contains, on return, one of the following "-> algebra -> variables -> types -> String"s: !Wtable_start !T+P + . --------------------------------------------------------------- particle Meaning --------------------------------------------------------------- electron An electron or a positron has been drifted ion An ion with charge +1 or -1 has been drifted unknown Neither electron nor ion --------------------------------------------------------------- !Wtable_end This argument must be modifiable. Any value this argument may have before the procedure call is lost. 3 path Contains on return the length in cm of the current drift-line, estimated as the sum of the linear distances between the successive steps of the drift-line. This argument must be modifiable. It will be of type "-> algebra -> variables -> types -> Number" after the call. Any value this argument may have before the procedure call is lost. 3 istat This argument contains on return the numeric "-> &DRIFT -> methods -> status" code for the last drift-line that was computed. This argument must be modifiable. It will be of type "-> algebra -> variables -> types -> Number" after the call. Any value this argument may have before the procedure call is lost. 3 status This argument contains on return the "-> &DRIFT -> methods -> status" "-> algebra -> variables -> types -> String" for the last drift-line. This argument must be modifiable. Any value this argument may have before the procedure call is lost. 3 nsteps Contains on return the number of steps in the last drift line that has been computed. This argument must be modifiable. It will be of type "-> algebra -> variables -> types -> Number" after the call. Any value this argument may have before the procedure call is lost. 3 technique Contains, on return, one of the following "-> algebra -> variables -> types -> String"s: !Wtable_start !T+P + . ----------------------------------------------------------------- particle Meaning ----------------------------------------------------------------- Runge-Kutta-Fehlberg Analytic integration of the mean trajectory Monte-Carlo Integration taking diffusion into account vacuum Integration in vacuum microscopic Molecular level tracking unknown None of the above ----------------------------------------------------------------- !Wtable_end This argument must be modifiable. Any value this argument may have before the procedure call is lost. 3 coordinate 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 "-> Call -> INTERNAL_TO_POLAR" procedure can be used to convert the coordinates. These arguments must be modifiable. They will be of type "-> algebra -> variables -> types -> Number" after the call. Any value these arguments may have before the procedure call is lost. 2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_ION("-> Call -> DRIFT_ION -> x", "-> Call -> DRIFT_ION -> y" [, "-> Call -> DRIFT_ION -> status" [, "-> Call -> DRIFT_ION -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_ION_3("-> Call -> DRIFT_ION_3 -> x", "-> Call -> DRIFT_ION_3 -> y" , "-> Call -> DRIFT_ION_3 -> z" [, "-> Call -> DRIFT_ION_3 -> status" [, "-> Call -> DRIFT_ION_3 -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 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 "-> &DRIFT -> methods -> Monte_Carlo". Format: !W
  CALL DRIFT_MC_ELECTRON("-> Call -> DRIFT_MC_ELECTRON -> x", "-> Call -> DRIFT_MC_ELECTRON -> y", "-> Call -> DRIFT_MC_ELECTRON -> z" [, "-> Call -> DRIFT_MC_ELECTRON -> status" [, "-> Call -> DRIFT_MC_ELECTRON -> time" ...
       [, "-> Call -> DRIFT_MC_ELECTRON -> multiplication" [, "-> Call -> DRIFT_MC_ELECTRON -> attachment"]]]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 3 multiplication See "-> Call -> DRIFT_ELECTRON -> multiplication". 3 attachment See "-> Call -> DRIFT_ELECTRON -> attachment". 2 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 "-> &GAS -> PARAMETERS -> sigma"). Multiplication and attachment losses are not evaluated. The Monte Carlo integration method is described in the drift section under "-> &DRIFT -> methods -> Monte_Carlo". Format: !W
  CALL DRIFT_MC_ION("-> Call -> DRIFT_MC_ION -> x", "-> Call -> DRIFT_MC_ION -> y", "-> Call -> DRIFT_MC_ION -> z" [, "-> Call -> DRIFT_MC_ION -> status" [, "-> Call -> DRIFT_MC_ION -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 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 "-> &GAS -> PARAMETERS -> sigma"). Multiplication and attachment losses are not evaluated. The Monte Carlo integration method is described in the drift section under "-> &DRIFT -> methods -> Monte_Carlo". Format: !W
  CALL DRIFT_MC_NEGATIVE_ION("-> Call -> DRIFT_MC_NEGATIVE_ION -> x", "-> Call -> DRIFT_MC_NEGATIVE_ION -> y", "-> Call -> DRIFT_MC_NEGATIVE_ION -> z" [, "-> Call -> DRIFT_MC_NEGATIVE_ION -> status" [, "-> Call -> DRIFT_MC_NEGATIVE_ION -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 DRIFT_MC_POSITRON Performs a Monte-Carlo calculation of an electron drift-line, assuming an inverted charge, 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 "-> &DRIFT -> methods -> status" (hit a wire, left the area etc). Note that the drift velocity vector is not anti-symmetric under charge inversion is there is a non-zero E-perpendicular component of the B field. 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 "-> &DRIFT -> methods -> Monte_Carlo". Format: !W
  CALL DRIFT_MC_POSITRON("-> Call -> DRIFT_MC_POSITRON -> x", "-> Call -> DRIFT_MC_POSITRON -> y", "-> Call -> DRIFT_MC_POSITRON -> z" [, "-> Call -> DRIFT_MC_POSITRON -> status" [, "-> Call -> DRIFT_MC_POSITRON -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 DRIFT_MICROSCOPIC_ELECTRON Performs a "-> &DRIFT -> methods -> microscopic" simulation of the movement of an electron through the gas. This procedure relies extensively on Magboltz. Before using this procedure, the Magboltz gas composition must be set - by running "-> &GAS -> MAGBOLTZ", by retrieving using "-> &GAS -> GET" gas tables that have been computed with Magboltz and which have been written in gas file format 10, or by using the "-> &GAS -> COMPOSITION" command. The step size in this procedure is the free path, as in the real gas, with its natural (exponential) distribution. A typical drift path therefore proceeds through millions of collisions and it is rarely practical to store each step individually. Instead, the electron location is recorded every n'th collision, where n is specified with the MONTE-CARLO-COLLISIONS parameters of the "-> &DRIFT -> INTEGRATION-PARAMETERS" command - n may be set to 1 if desired. In order to profit fully from the detailed nature of these calculations, it is advisable, in case the electrons head for a wire, to set the "-> &DRIFT -> INTEGRATION-PARAMETERS -> TRAP-RADIUS" to 1. Each collision is classified as either elastic, inelastic, super-elastic, attachment or ionisation, with one of the species of molecules present in the gas mixture. In case of attachment, the electron is not tracked any further and the "-> &DRIFT -> methods -> status" is set accordingly. In this procedure, additional electrons produced through ionisation are not tracked. Use "-> Call -> MICROSCOPIC_AVALANCHE" if this is desired. Format: !W
  CALL DRIFT_MICROSCOPIC_ELECTRON("-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> x", "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> y", "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> z" ...
     [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> status" [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> time" [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> options" ...
     [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum" [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_start" [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> dir"_x, dir_y, dir_z ...
     [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> distribution", [, "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> rates"]]]]]]]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 3 options A "-> algebra -> variables -> types -> String" which may contain one or more of the following options and their negated version (prefix with NO): !Wdl_start !T+ + ----------------------------------------------------------------------------------- Option Description ----------------------------------------------------------------------------------- MARK-ATTACHMENT Marks the location where attachment occurs with representation "-> graphics -> REPRESENTATION -> item -> ATTACHMENT". The electron will as a rule stop at these locations. MARK-ELASTIC Marks the locations of elastic interactions, using "-> graphics -> REPRESENTATION -> item -> ELASTIC". This is nearly always the most common type of collision. MARK-EXCITATION Marks the locations of inelastic collisions where an excited state is produced. The point will be drawn using "-> graphics -> REPRESENTATION -> item -> EXCITATION". MARK-INELASTIC Marks the locations of inelastic but non-exciting interactions. The position will be marked using "-> graphics -> REPRESENTATION -> item -> INELASTIC". MARK-IONISATION Marks the locations where ionisations occur using "-> graphics -> REPRESENTATION -> item -> IONISATION". MARK-SUPER-ELASTIC Marks the locations of super-elastic interactions using "-> graphics -> REPRESENTATION -> item -> SUPER-ELASTIC". PRINT Switches on Magboltz printing. Use the "-> OPTIONS -> DEBUG" option to obtain details for each step. ----------------------------------------------------------------------------------- !Wdl_end Note: switching on any of the MARK options presumes that you have already opened a graphics window suitable for plotting the drift-line. Example: !W
   Call "-> Call -> plot_drift_area"
   Call "-> Call -> new_track"
   "-> Do"
      Call "-> Call -> get_cluster"(x,y,z,n,e,done)
      If done Then "-> Do -> Leave"
      Call drift_microscopic(x, y, z, status, time, ...
         `mark-ion  mark-att`, ...
         5.0, 0.1, 0,0,0, histe)
      Say "Status = {status}, Drift time = {time} microsec"
      Call "-> Call -> plot_drift_line"
   Enddo
   Call "-> Call -> plot_track"
   Call "-> Call -> plot_end"
!W
In this example, all electrons generated along a track are traced and plotted, marking locations where ionisation and attachment occurs. 3 e_maximum Maximum kinetic energy in eV the electron is expected to reach during the trajectory. The calculation of the electron trajectory is aborted with "-> &DRIFT -> methods -> status" "Energy exceeds E_maximum" if at any point the electron energy exceeds this value. The trajectory will be inaccurate if the maximum energy is chosen too large. The simplest way to find suitable values for this parameter is running "-> &GAS -> MAGBOLTZ" with the "-> &GAS -> MAGBOLTZ -> PLOT-DISTRIBUTION-FUNCTIONS" option switched on. Beware that e_maximum must be suitable over the entire drift path of the electron, which may include a high field region in the vicinity of an anode. [Default: 5 eV] 3 e_start Kinetic energy in eV of the electron at the start of the trajectory. This energy must be strictly positive (non-zero) and less than "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum". [Default: 2\ % of "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum".] 3 dir Direction vector of the initial velocity of the electron. The initial direction has, in most gaseous detectors, little impact. The norm of the initial velocity is taken from "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_start", not from the direction vector. The normalisation is arbitrary. All three components must be specified. If all 3\ components of the direction vector are zero, then an isotropic random vector will be generated. [A random direction is assumed if no direction is specified.] 3 distribution On return an "-> algebra -> variables -> types -> Histogram" which contains the electron energy distribution sampled just prior to every interaction with the gas molecules. If this argument is on entry an existing histogram, then new entries will be added to it. This can be used to force a scale and also to accumulate statistics across multiple calls. If this argument is of another type on entry, then the current value will be deleted and a new histogram will be booked with 100\ bins and ranging from 0 to "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum". 3 rates This procedure returns the detailed counts of the interactions in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". The cross sections present in the vector vary with "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum" since Magboltz eliminates, for reasons of efficiency, negligibly small cross section terms. The various terms can be identified with the help of the "-> Call -> CROSS_SECTION_IDENTIFIER" procedure: !W
  Call drift_microscopic(x, y, z, status, time, ``, ...
     100.0, 4.0, 0,0,0, histe, vec)
  For i From 1 To "-> algebra -> functions -> size"(vec) Do
     Call "-> Call -> cross_section_identifier"(i, level, type)
     Say "Level {i} = {level}, count = {"-> algebra -> functions -> number"(vec[i])}, type = {type}"
  Enddo
!W
2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_NEGATIVE_ION("-> Call -> DRIFT_NEGATIVE_ION -> x", "-> Call -> DRIFT_NEGATIVE_ION -> y" [, "-> Call -> DRIFT_NEGATIVE_ION -> status" [, "-> Call -> DRIFT_NEGATIVE_ION -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_NEGATIVE_ION_3("-> Call -> DRIFT_NEGATIVE_ION_3 -> x", "-> Call -> DRIFT_NEGATIVE_ION_3 -> y", "-> Call -> DRIFT_NEGATIVE_ION_3 -> z" [, "-> Call -> DRIFT_NEGATIVE_ION_3 -> status" [, "-> Call -> DRIFT_NEGATIVE_ION_3 -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 DRIFT_POSITRON Calculates an electron drift-line, assuming a positive charge, from the point (x, y, 0) and returns the drift time and the "-> &DRIFT -> methods -> status" (hit a wire, left the area etc). Note that the drift velocity vector is not anti-symmetric under charge inversion is there is a non-zero E-perpendicular component of the B field. 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_POSITRON("-> Call -> DRIFT_POSITRON -> x", "-> Call -> DRIFT_POSITRON -> y" [, "-> Call -> DRIFT_POSITRON -> status" [, "-> Call -> DRIFT_POSITRON -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> &DRIFT -> methods -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 DRIFT_POSITRON_3 Calculates an electron drift-line, assuming a positive charge, from the point (x, y, z) and returns the drift time and the "-> &DRIFT -> methods -> status" (hit a wire, left the area etc). Note that the drift velocity vector is not anti-symmetric under charge inversion is there is a non-zero E-perpendicular component of the B field. 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integration method. Format: !W
  CALL DRIFT_POSITRON_3("-> Call -> DRIFT_POSITRON_3 -> x", "-> Call -> DRIFT_POSITRON_3 -> y", "-> Call -> DRIFT_POSITRON_3 -> z" [, "-> Call -> DRIFT_POSITRON_3 -> status" [, "-> Call -> DRIFT_POSITRON_3 -> time"]])
!W
3 x See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> &DRIFT -> methods -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 2 DRIFT_DIVERGENCE Returns the local divergence of the drift field. This is a instruction used to debug the diffusion calculation, the procedure is not of much general use. Format: !W
  CALL DRIFT_DIVERGENCE(x, y, z, "-> Call -> DRIFT_DIVERGENCE -> f"1, f2, f3 [, "-> Call -> DRIFT_DIVERGENCE -> options"])
!W
Example: !W
  "-> &CELL"
  "-> &CELL -> tube" r=1
  "-> &CELL -> rows"
  s 1 0.01  0 0 1000

  "-> &GAS"
  "-> &GAS -> table" drift-velocity=ep/100

  "-> &DRIFT"
  "-> Global" step=0.0010
  "-> &DRIFT -> integration-parameters" m-c-dist {step}
  Call "-> Call -> book_matrix"(xv,100)
  Call "-> Call -> book_matrix"(f1v,100)
  Call "-> Call -> book_matrix"(f2v,100)
  "-> Global" n=0
  Global phi=335*pi/180
  For x From 0.01 Step 0.02 To 0.99 Do
     Call drift_divergence(x*"-> algebra -> functions -> cos"(phi), x*"-> algebra -> functions -> sin"(phi), 0, ...
        f1, f2, f3, `positive,electron`)
     Global n=n+1
     Global xv[n]=x
     Global f1v[n]=f1
     Global f2v[n]=f2
  Enddo
  Call "-> Call -> adjust_matrix"(xv,n,0)
  Call "-> Call -> adjust_matrix"(f1v,n,0)
  Call "-> Call -> adjust_matrix"(f2v,n,0)
  Global min="-> algebra -> functions -> minimum"(f1v&f2v)
  Global max="-> algebra -> functions -> maximum"(f1v&f2v)
  Call "-> Call -> plot_frame"(0,0.95*min,1,1.05*max,`r`,`f`,`Divergence`)
  Call "-> Call -> plot_line"(xv,f1v,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_line"(xv,f2v,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
  Call "-> Call -> plot_line"(xv,1+step/xv,`"-> graphics -> REPRESENTATION -> item -> function-3"`)
  Call "-> Call -> plot_end"
!W
This example computes the divergence of the drift field in a round tube with a gas of constant mobility. The product of f1 and f2 should be equal to 1 in this case. With a gas of constant drift velocity, f1 should be constant but not f2. The curve drawn with representation FUNCTION-3 shows the exact expression of the transverse divergence. 3 f The divergence is computed along 3 perpendicular axes: !Wul_start - f1: along the axis of the drift velocity; - f2: along the axis (-v2,v1,0) if |v3| is the smallest component of the velocity, along (-v3,0,v1) if |v2| is smallest and along (0,v3,-v2) if |v1| is smallest; - f3: along the vectorial product of the first 2 axes. !Wul_end Although there can be correlations between these divergences, they are not computed. 3 options A character "-> algebra -> variables -> types -> String" string which contains one or more of the following options: !Wtable_start !T+P + + . -------------------------------------------------------- option Meaning Default -------------------------------------------------------- ELECTRON Divergence for electrons Default ION Divergence for ions Electron is default POSITIVE Positive charge Negative is default NEGATIVE Negative charge Default -------------------------------------------------------- !Wtable_end 2 DRIFT_ROTATION Returns the local rotation matrices of the drift field. This is a instruction used to debug the diffusion calculation, the procedure is not of much general use. Format: !W
  CALL DRIFT_ROTATION(x, y, z, "-> Call -> DRIFT_ROTATION -> R"vc, Rmc, Rvm [, "-> Call -> DRIFT_ROTATION -> options"])
!W
Example: !W
  "-> &CELL"
  "-> &CELL -> tube" r=1
  "-> &CELL -> rows"
  s 1 0.01  0 0 1000

  "-> &MAGNETIC"
  "-> &MAGNETIC -> components" 0 0 1 T

  "-> &GAS"
  "-> &GAS -> table" drift-velocity=100

  "-> &DRIFT"
  "-> &DRIFT -> integration-parameters" m-c-dist 0.001
  Call drift_rotation(0.1, 0.0, 0,rvc,rmc,rvm,`electron,positive`)
  Call "-> Call -> print_matrix"(rvc,rmc,rvm)
!W
3 R Each of the 3 return arguments is a 3\×3 "-> algebra -> variables -> types -> Matrix". They contain matrices used to transform between the 3 coordinate systems used for diffusion calculations: !Wdl_start !T+ + --------------------------------------------------------------------- System Description --------------------------------------------------------------------- Internal Usually Cartesian but possibly a conformal mapping thereof. Magboltz Frame used by Magboltz to compute transport parameters: (E, Btrans, E\×B) where Btrans is the part of B that is transverse to E, if there is such a component. Otherwise the 2nd and 3rd axis are any 2 axes perpendicular to E and perpendicular to each other. Velocity First axis is the local velocity vector, the 2 other axes are perpendicular to each other and to the velocity. --------------------------------------------------------------------- !Wdl_end All coordinate systems are right-handed. The rotation matrices are written as follows: !Wdl_start !T+ + --------------------------------------------------------------------- Matrix Description --------------------------------------------------------------------- Rvc From the velocity frame to the internal coordinate system Rmc From the Magboltz frame to internal coordinates Rvm From the velocity frame to the Magboltz frame --------------------------------------------------------------------- !Wdl_end These arguments do not need to be initialised before the procedure is called. Any value assigned to the arguments before the call will be lost afterwards. 3 options A character "-> algebra -> variables -> types -> String" string which contains one or more of the following options: !Wtable_start !T+P + + . -------------------------------------------------------- option Meaning Default -------------------------------------------------------- ELECTRON Rotation for electrons Default ION Rotation for ions Electron is default POSITIVE Positive charge Negative is default NEGATIVE Negative charge Default -------------------------------------------------------- !Wtable_end 2 DRIFT_VELOCITY Returns the magnitude of the drift velocity vector for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In this case, the values returned by this procedure coincide with those returned by "-> Call -> VELOCITY_E". In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. The velocity that is returned is equal to the vectorial sum of "-> Call -> VELOCITY_E", "-> Call -> VELOCITY_BTRANSVERSE" and "-> Call -> VELOCITY_ExB". Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the drift velocity is returned in cm/\μsec. Formats: !W
  CALL DRIFT_VELOCITY(e, drift)
  CALL DRIFT_VELOCITY(ex, ey, ez, drift)
  CALL DRIFT_VELOCITY(ex, ey, ez, bx, by, bz, drift)
!W
Example: !W
  "-> Global" emin=100
  "-> Global" emax=10000
  "-> Global" e=emin*(emax/emin)^(("-> algebra -> functions -> row"(200)-1)/199)
  "-> &GAS"
  "-> &GAS -> mix" argon 95 methane 5 noplot-f0 noplot-cross-section e/p-range {emin/760,emax/760}
  "-> &MAIN"
  Call drift_velocity(0,0,e,vd5)
  "-> &GAS"
  "-> &GAS -> mix" argon 90 methane 10 noplot-f0 noplot-cross-section e/p-range {emin/760,emax/760}
  "-> &MAIN"
  Call drift_velocity(0,0,e,vd10)
  "-> &GAS"
  "-> &GAS -> mix" argon 80 methane 20 noplot-f0 noplot-cross-section e/p-range {emin/760,emax/760}
  "-> &MAIN"
  Call drift_velocity(0,0,e,vd20)

  Call "-> Call -> plot_frame"(emin,0,emax,10,`E [V/cm]`, ...
     `vD [cm/microsec]`, ...
     `Drift velocity in Ar/CH4 mixtures`)
  Call "-> Call -> plot_line"(e,vd5,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_line"(e,vd10,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
  Call "-> Call -> plot_line"(e,vd20,`"-> graphics -> REPRESENTATION -> item -> function-3"`)
  Call "-> Call -> plot_end"
!W
2 ELECTRIC_FIELD Returns the electric field vector and the potential at a given point. This procedure assumes that the z-coordinate of the point is equal to 0. The arguments ex, ey, ez, e, v and status are optional. Format: !W
  CALL ELECTRIC_FIELD("-> Call -> ELECTRIC_FIELD -> x", "-> Call -> ELECTRIC_FIELD -> y", "-> Call -> ELECTRIC_FIELD -> ex", "-> Call -> ELECTRIC_FIELD -> ey", "-> Call -> ELECTRIC_FIELD -> ez", "-> Call -> ELECTRIC_FIELD -> e", "-> Call -> ELECTRIC_FIELD -> v", "-> Call -> ELECTRIC_FIELD -> status")
!W
Example: !W
  "-> &CELL"
  "-> &CELL -> plane" x=-1
  plane y=-1
  "-> &CELL -> rows"
  s * * 1 1 1000

  "-> &FIELD"
  "-> Global" n=6
  Call "-> Call -> book_matrix"(x,n,n)
  Call "-> 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 "-> Call -> print_matrix"(x,y,ex,ey,ez,e,v,stat)
  "-> &FIELD -> area" 0 0 1 1
  "-> &FIELD -> grid" {n}
  "-> &FIELD -> print" ex ey e v
!W
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. 3 x This procedure accepts input arguments of types "-> algebra -> variables -> types -> Number" and "-> algebra -> variables -> types -> Matrix". This argument is not modified. 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: !W
  for x: log(r)
  for y: \φ, in radians
!W
These mappings can be performed with the "-> Call -> POLAR_TO_INTERNAL" procedure. 3 y See "-> Call -> ELECTRIC_FIELD -> x". 3 ex 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: !W
  Er = Ex/r
  Ephi = Ey/r
  Ez is invariant
!W
This argument must be modifiable and its value prior to the call will be overwritten. On return, the argument will be of type "-> algebra -> variables -> types -> Matrix" if either of the coordinates is of that type, otherwise it will be of type "-> algebra -> variables -> types -> Number". 3 ey See "-> Call -> ELECTRIC_FIELD -> ex". 3 ez See "-> Call -> ELECTRIC_FIELD -> ex". 3 e See "-> Call -> ELECTRIC_FIELD -> ex". 3 v Contains on successful completion, the potential in Volt. See also "-> Call -> ELECTRIC_FIELD -> ex". 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 "-> algebra -> variables -> types -> Matrix", then a matrix filled with numeric location codes is returned. !Wtable_start !T+P + R . --------------------------------------------------------------------------- Status Location string Numeric --------------------------------------------------------------------------- In a material Inside the mesh, but not in a drift medium -5 In X-wire N Inside wire number N of type X 1-MXWIRE In X-solid N Inside solid number N of type X > 2*MXWIRE 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 --------------------------------------------------------------------------- !Wtable_end 2 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: !W
  CALL ELECTRIC_FIELD_3(x, y, z, ex, ey, ez, e, v, status)
!W
Example: See "-> Call -> ELECTRIC_FIELD". 3 coordinates This procedure accepts input arguments of types "-> algebra -> variables -> types -> Number" and "-> algebra -> variables -> types -> Matrix". If at least one of the input arguments x, y, z is of type "-> algebra -> variables -> types -> 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 "-> algebra -> variables -> types -> 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: z
!W
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 "-> Call -> POLAR_TO_INTERNAL" procedure. 3 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: !W
  Er = Ex/r
  Ephi = Ey/r
  Ez is invariant
!W
3 status See "-> Call -> ELECTRIC_FIELD -> status". 2 ELECTRON_VELOCITY Returns the electron "-> &DRIFT -> methods -> velocity" vector at a point. This procedure needs electron drift velocity data, which can be computed with the "-> &GAS -> 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 "-> &DRIFT -> SPEED" command. Format: !W
  CALL ELECTRON_VELOCITY(x, y, z, vx, vy, vz [, status])
!W
Example: !W
  Call electron_velocity(2,3,0,vx,vy,vz,status)
  Say "Velocity: ({vx,vy,vz}), Status: {status}"
!W
3 coordinates This procedure accepts coordinates of type "-> algebra -> variables -> types -> 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: z
!W
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 "-> Call -> POLAR_TO_INTERNAL" procedure. 3 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: !W
  vr = vx/r
  vphi = vy/r
  vz is invariant
!W
3 status See "-> Call -> ELECTRIC_FIELD -> status". 2 EXCITATION_IDENTIFIER Returns the identifier of an excitation level. This procedure is used to identify the rates that are returned by "-> Call -> INTEGRATE_EXCITATIONS". The first argument is the level number, the index of the vector given by INTEGRATE_EXCITATIONS. The second argument contains on return a string with the level identifier, which is described in somewhat more detail in the gas "-> &GAS -> MAGBOLTZ -> ingredient"s. The optional third argument contains on return the threshold energy of the level (in eV). The number of levels can be obtained with "-> CALL -> LEVEL_COUNT". Format: !W
  CALL EXCITATION_IDENTIFIER(level_number, level_identifier [, level_energy])
!W
For examples, see "-> Call -> INTEGRATE_EXCITATIONS" and "-> Call -> LEVEL_COUNT". 2 EXCITATION_RATE Returns the rate at which an excited state is formed, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the rates (at least in principle) depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The first argument is a "-> algebra -> variables -> types -> Number" which identifies the level. The number of available levels can be found with the "-> Call -> LEVEL_COUNT" procedure and further information can be obtained with "-> Call -> EXCITATION_IDENTIFIER". The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the rate is returned in THz. Formats: !W
  CALL EXCITATION_RATE(level, e, rate)
  CALL EXCITATION_RATE(level, ex, ey, ez, rate)
  CALL EXCITATION_RATE(level, ex, ey, ez, bx, by, bz, rate)
!W
Example: !W
  "-> Global" emin=5000
  "-> Global" emax=25000
  "-> Global" e=emin*(emax/emin)^(("-> algebra -> functions -> row"(200)-1)/199)
  Call "-> Call -> plot_frame"(emin/1000, 0, emax/1000, 2, `E [kV/cm]`, ...
     `Excitation rate [GHz]`, `Excitations and Dissociations`)
  Call "-> Call -> level_count"(nexc, nion)
  For id From 1 To nexc Do
     Call excitation_rate(id,e,exc)
     Call "-> Call -> excitation_identifier"(id, name, ethresh)
     Say "{id}: {name}, Emin = {ethresh}"
     Call "-> Call -> string_index"(name,`DISS`,ind)
     If ind>0 Then
        Call "-> Call -> plot_line"(e/1000,exc*1e3, `"-> graphics -> REPRESENTATION -> item -> function-2"`)
     Else
        Call "-> Call -> plot_line"(e/1000,exc*1e3, `"-> graphics -> REPRESENTATION -> item -> function-3"`)
     Endif
  Enddo
  Call "-> Call -> plot_end"
!W
This examples plots all excitation rates, and marks the dissociations using a different line type. 2 EXTRACT_SUBMATRIX Extracts a sub-matrix 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: !W
  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)
!W
2 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 "-> Call -> EXTREMUM -> options". When the search is successful, the global variable "-> algebra -> variables -> predefined -> OK" is set to True, otherwise to False. The following conditions can lead to un unsuccessful search: !Wul_start - multiple extrema with (nearly) identical function values, such as the sine function; - an extremum which is far from being parabolic; - search for a minimum while the function has a maximum, or vv; - minimum or maximum located very near to, but not on, the limit of the search range; - too strict convergence criteria. !Wul_end 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 for functions: !W
  CALL EXTREMUM("-> Call -> EXTREMUM -> function", "-> Call -> EXTREMUM -> extremum", "-> Call -> EXTREMUM -> minimum", "-> Call -> EXTREMUM -> maximum", ...
       [ "-> Call -> EXTREMUM -> options" [, "-> Call -> EXTREMUM -> \ε_loc" [, "-> Call -> EXTREMUM -> \ε_fun" [, "-> Call -> EXTREMUM -> itermax" ]]]])
!W
Format for matrices: !W
  CALL EXTREMUM("-> Call -> EXTREMUM -> ordinates", "-> Call -> EXTREMUM -> values", "-> Call -> EXTREMUM -> extremum", ...
       [ "-> Call -> EXTREMUM -> options" [, "-> Call -> EXTREMUM -> \ε_loc" [, "-> Call -> EXTREMUM -> \ε_fun" [, "-> Call -> EXTREMUM -> itermax" ]]]])
!W
Examples: !W
  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}"
!W
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. !W
  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}."
!W
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. 3 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 "-> algebra -> variables -> types -> Number". This argument is mandatory and should be of the type "-> algebra -> variables -> types -> String". 3 ordinates A 1-dimensional "-> algebra -> variables -> types -> Matrix" which contains the ordinates. This vector must have the same length as the "-> Call -> EXTREMUM -> values" and the length must be at least 2. This argument is mandatory. 3 values A 1-dimensional "-> algebra -> variables -> types -> Matrix" which contains the values. This vector must have the same length as the "-> Call -> EXTREMUM -> ordinates" and the length must be at least 2. This argument is mandatory. 3 extremum 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 "-> algebra -> variables -> types -> Number". The variable may be modified even if the search fails. This argument should be a global variable, not an expression nor a constant. 3 minimum The lower end of the parameter range to be searched for an extremum. This argument is mandatory for an extremum search on a function and must then be of the type "-> algebra -> variables -> types -> Number". The argument should not be specified when searching vectors. 3 maximum The upper end of the parameter range to be searched for an extremum. This argument is mandatory for an extremum search on a function and must then be of the type "-> algebra -> variables -> types -> Number". The argument should not be specified when searching vectors. 3 options A "-> algebra -> variables -> types -> String" that can contain zero or more of the following options, separated by commata or blanks: !Wtable_start !T+P + + . ------------------------------------------------------------ Option Effect Notes ------------------------------------------------------------ CUBIC Cubic vector interpolation Only with vectors LINEAR Linear vector interpolation Only with vectors 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 QUADRATIC Quadratic vector interpolation Only with vectors ------------------------------------------------------------ !Wtable_end 3 \ε_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 \ε_loc or absolutely by less than an amount \ε_loc. This is an optional parameter of type "-> algebra -> variables -> types -> Number". Since the function is evaluated in single precision arithmetic, values less than 10\-6\ are not meaningful on most computers. [By default 10\-4\.] 3 \ε_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 \ε_fun or absolutely by less than an amount \ε_fun. This is an optional parameter of type "-> algebra -> variables -> types -> Number". Since the function is evaluated in single precision arithmetic, values less than 10\-6\ are not meaningful on most computers. [By default 10\-4\.] 3 itermax Maximum number of parabolic search loops. The search is abandoned if it has not converged on the basis of "-> Call -> EXTREMUM -> \ε_loc" or "-> Call -> EXTREMUM -> \ε_fun" within the specified number of iterations, This is an optional parameter of type "-> algebra -> variables -> types -> Number". [By default 20.] 2 FILL_HISTOGRAM This procedure adds entries to an existing histogram. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if filling was successful and to False if it wasn't, usually because the histogram to be filled didn't exist. OK is not set to False if the entry is out of range. Format: !W
  CALL FILL_HISTOGRAM("-> Call -> FILL_HISTOGRAM -> histogram", "-> Call -> FILL_HISTOGRAM -> entry" [, "-> Call -> FILL_HISTOGRAM -> weight"])
!W
Example: !W
  Call "-> Call -> book_histogram"(ref,100)
  For i From 1 To 10000 Do
     Call fill_histogram(ref,rnd_landau)
  Enddo
  Call "-> Call -> plot_histogram"(ref,`Energy loss`,`Landau distribution`)
  Call "-> Call -> plot_end"
!W
This example could be used to check that the Landau random number generator does indeed work. 3 histogram An histogram is referenced via a global variable that should be seen as the histogram itself. Such variables are of "-> algebra -> variables -> types -> Histogram". Usually, they are created by calling "-> Call -> BOOK_HISTOGRAM" to explicitly create a new histogram, or by calling "-> Call -> GET_HISTOGRAM" to retrieve an existing histogram from a file. They can also be the result of arithmetic between histograms. This argument should not be an expression since this would result in adding entries to a temporary histogram. [This is a mandatory argument] 3 entry This argument should be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> Matrix". In the former case, a single entry is added. In the latter case, all elements of the Matrix are treated as entries. If you supply a Matrix type argument, then ensure that the "-> Call -> FILL_HISTOGRAM -> weight" is either a Number or a Matrix of the same overall length as the entries. All Matrix shapes are permitted. The shapes of the entry and weight matrices do not have to be the same. [This argument is mandatory.] 3 weight This argument should be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> Matrix". In the former case, the same weight is applied to all entries. In the latter case, the elements of the Matrix are treated as individual weights for the entries. If you supply a Matrix type argument, then ensure that the "-> Call -> FILL_HISTOGRAM -> entry" is either a Number or a Matrix of the same length as the weights. All Matrix shapes are permitted. Moreover, the shapes of the entries and the weights do not have to be the same, [This argument is mandatory is optional and defaults to 1.] 2 FIT_EXPONENTIAL Fits an exponential of a polynomial to an histogram or to 1-dimensional matrices. In addition to the parameters, the global variable "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Format for histograms: !W
  CALL FIT_EXPONENTIAL("-> Call -> FIT_EXPONENTIAL -> reference", "-> Call -> FIT_EXPONENTIAL -> a"0, a1, a2, ..., an, ...
       "-> Call -> FIT_EXPONENTIAL -> err_a"0, err_a1, err_a2, ..., err_an [, "-> Call -> FIT_EXPONENTIAL -> options"])
!W
Format for matrices: !W
  CALL FIT_EXPONENTIAL("-> Call -> FIT_EXPONENTIAL -> x", "-> Call -> FIT_EXPONENTIAL -> y", "-> Call -> FIT_EXPONENTIAL -> err_y", "-> Call -> FIT_EXPONENTIAL -> a"0, a1, a2, ..., an, ...
       "-> Call -> FIT_EXPONENTIAL -> err_a"0, err_a1, err_a2, ..., err_an [, "-> Call -> FIT_EXPONENTIAL -> options"])
!W
Examples: !W
  "-> &SIGNAL"
  "-> &SIGNAL -> avalanche" "-> &SIGNAL -> avalanche -> polya-townsend" 0.5
  "-> &SIGNAL -> 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}."
!W
In this example, the user wishes to see how well a Polya distribution with parameter \θ=0.5, can be reproduced by an exponential. !W
  "-> Vector" ep      ap
         0.13158 0
         0.65789 0
         1.31579 0
         2.63158 0
         6.57895 0
        13.1579  0.0089211
        19.7368  0.10592
        26.3158  0.24737
        39.4737  0.62105
        52.6316  0.97995
        78.9474  1.86895
       105.263   2.74474
       131.579   3.605
       197.368   5.515
       230.263   6.39237
       300       8.07711

  "-> Global" epfit=ep[6,7,8,9]
  Global apfit=ap[6,7,8,9]

  Global p=760
  Call fit_exponential(1/epfit,apfit,0.1*apfit,a0,a1,ea0,ea1, ...
     `noplot,noprint`)

  Global emin=5000
  Global emax=300000
  Global ne=100
  Global ekorff=emin*(emax/emin)^(("-> algebra -> functions -> row"(ne)-1)/(ne-1))
  Global akorff="-> algebra -> functions -> exp"(a0+a1*p/ekorff)*p
  !"-> graphics -> options" log-x log-y
  Call "-> Call -> plot_frame"(emin,0.1,emax,8000,`E [V/cm]`,`α [1/cm]`, ...
     `Korff fit`)
  Call "-> Call -> plot_error_bar"(ep*p,ap*p)
  Call "-> Call -> plot_line"(ekorff,akorff,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Global a="-> algebra -> functions -> exp"(a0)
  Global ea=ea0*a
  Global a="-> algebra -> functions -> entier"(a*10)/10
  Global ea="-> algebra -> functions -> entier"(ea*10)/10
  Global b=-"-> algebra -> functions -> entier"(a1)
  Global eb="-> algebra -> functions -> entier"(ea1)
  Call "-> Call -> plot_text"(40000,100,`A = `/"-> algebra -> functions -> string"(a)/` ± `/string(ea), ...
     `title`)
  Call "-> Call -> plot_text"(40000,60,`B = `/string(b)/` ± `/string(eb), ...
     `title`)
  Call "-> Call -> plot_end"
!W
The Townsend coefficients are sometimes approximated using the Rose-Korff formula: !W
  \α/p = A.exp(-B.p/E)
!W
This example performs such a fit on Townsend coefficients that have been computed by the Imonte program for a mixture of 90\ % argon and 10\ % isobutane. Imonte is a precursor program for Magboltz version\ 7 and is no longer used. 3 reference The histogram is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or "-> Call -> GET_HISTOGRAM". This argument may also be an expression that results in a histogram. The argument is not modified on return. 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. 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. 3 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. 3 a The function that is fitted to the data points is given by !W
  function = exp(polynomial)
!W
where !W
  polynomial = a\0\ + a\1\*x + a\2\*x\2\ + a\3\*x\3\ + ... + a\n\*x\n\
!W
The arguments a\0\, a\1\ 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. 3 err_a The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. 3 options The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitly provided in that case. 2. The plot is always made on a linear-logarithmic scale. !Wol_end 2 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 "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Format for histograms: !W
  CALL FIT_FUNCTION(reference, function, ...
       par1, par2, par3, ... , err1, err2, err3, ... [, options])
!W
Format for matrices: !W
  CALL FIT_FUNCTION(x, y, err_y, function, ...
       par1, par2, par3, ... , err1, err2, err3, ... [, options])
!W
Example: !W
  Call "-> Call -> book_histogram"(ref,50,-1,3)
  For i From 1 To 500 Do
     "-> Global" x=-1+4*"-> algebra -> functions -> rnd_uniform"
     Global w=x^2+1
     Call "-> 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)}"
!W
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. Another example can be found in the description of the "-> algebra -> functions -> RND_POISSON" random number generator. 3 function The function that should be fitted is entered as a character "-> algebra -> variables -> types -> 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 "-> algebra -> variables -> types -> 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. 3 reference The "-> algebra -> variables -> types -> Histogram" is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or to "-> Call -> GET_HISTOGRAM". This argument may also be an expression that results in a histogram. The argument is not modified on return. 3 x A 1-dimensional "-> algebra -> variables -> types -> Matrix" 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. 3 y A 1-dimensional "-> algebra -> variables -> types -> Matrix" 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. 3 err_y A 1-dimensional "-> algebra -> variables -> types -> Matrix" 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. 3 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 "-> algebra -> variables -> types -> 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 "-> algebra -> variables -> types -> Undefined" if the fit fails. 3 errors The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. 3 options The options "-> algebra -> variables -> types -> String" may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end Note: !Wol_start 1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitly provided in that case. 2. The plot is always made on a linear-logarithmic scale. !Wol_end 2 FIT_GAUSSIAN Fits a Gaussian distribution to a set of 1-dimensional matrices or to an histogram. In addition to the parameters, the global variable "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Format for histograms: !W
  CALL FIT_GAUSSIAN("-> Call -> FIT_GAUSSIAN -> reference", "-> Call -> FIT_GAUSSIAN -> integral", "-> Call -> FIT_GAUSSIAN -> mean", "-> Call -> FIT_GAUSSIAN -> sigma" ...
       [, "-> Call -> FIT_GAUSSIAN -> error"_int [, error_mean [, error_sigma [, "-> Call -> FIT_GAUSSIAN -> options"]]]])
!W
Format for matrices: !W
  CALL FIT_GAUSSIAN("-> Call -> FIT_GAUSSIAN -> x", "-> Call -> FIT_GAUSSIAN -> y", "-> Call -> FIT_GAUSSIAN -> err_y", "-> Call -> FIT_GAUSSIAN -> integral", "-> Call -> FIT_GAUSSIAN -> mean", "-> Call -> FIT_GAUSSIAN -> sigma" ...
       [, "-> Call -> FIT_GAUSSIAN -> error"_int [, error_mean [, error_sigma [, "-> Call -> FIT_GAUSSIAN -> options"]]]])
!W
Example 1: !W
  Call "-> 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}."
!W
The "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" instruction returns the RMS of the arrival time distributions. To obtain Gaussian fits in addition, you can specify the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-HISTOGRAMS" option and then use FIT_GAUSSIAN. You can also do the fit in a separate job as explained in http://cern.ch/garfield/examples/ Example 2: !W
  Call "-> Call -> book_histogram"(hist)
  For i From 1 To 10000 Do
     Global sum=0
     For j From 1 To 12 Do
        Global sum=sum+"-> algebra -> functions -> rnd_uniform"
     Enddo
     Call "-> Call -> fill_histogram"(hist,sum)
  Enddo
  Call fit_gaussian(hist,a,b,c,ea,eb,ec,`print,plot`)
!W
(This verifies the approximation of a Gaussian distribution by the sum of 12 uniformly distributed random numbers.) 3 reference Should contain on entry the "-> algebra -> variables -> types -> Histogram" to be fitted. This is usually a global variable that has been returned by a call to "-> Call -> BOOK_HISTOGRAM" or to "-> Call -> GET_HISTOGRAM". This argument may also be an expression that results in a histogram. The argument is not modified by the procedure. [Mandatory argument.] 3 x Should contain on entry a 1-dimensional "-> algebra -> variables -> types -> Matrix" in which the abscissa are stored of the points on which the fit is to be performed. This vector should have the same size as "-> Call -> FIT_GAUSSIAN -> y". The argument is not modified by the procedure. [Mandatory argument.] 3 y Should contain on entry a 1-dimensional "-> algebra -> variables -> types -> Matrix" in which the function values are stored of the points on which the fit is to be performed. This vector should have the same size as "-> Call -> FIT_GAUSSIAN -> x". The argument is not modified by the procedure. [Mandatory argument.] 3 err_y Should contain on entry the errors on the function values. These errors can either be specified in the form of a single "-> algebra -> variables -> types -> Number", which is interpreted as a common error for all function values, or in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix" of errors for each point separately. If a Matrix type argument is used, then it must have the same length as "-> Call -> FIT_GAUSSIAN -> x" and "-> Call -> FIT_GAUSSIAN -> y". The argument is not modified by the procedure. [Mandatory argument.] 3 integral Contains on successful completion 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. The argument will be of type "-> algebra -> variables -> types -> Number". [Mandatory argument.] 3 mean Contains on successful completion 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. The argument will be of type "-> algebra -> variables -> types -> Number". [Mandatory argument.] 3 sigma Contains on successful completion 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. The argument will be of type "-> algebra -> variables -> types -> Number". [Mandatory argument.] 3 error The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. All errors are of type "-> algebra -> variables -> types -> Number". 3 options The options "-> algebra -> variables -> types -> String" may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end 2 FIT_MATHIESON Fits a integrated Mathieson distribution to an histogram or to a set of matrices. 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 "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Formats: !W
  CALL FIT_MATHIESON("-> Call -> FIT_MATHIESON -> x", "-> Call -> FIT_MATHIESON -> y", "-> Call -> FIT_MATHIESON -> err_y", "-> Call -> FIT_MATHIESON -> distance", "-> Call -> FIT_MATHIESON -> norm", "-> Call -> FIT_MATHIESON -> centre", "-> Call -> FIT_MATHIESON -> k3", ...
       "-> Call -> FIT_MATHIESON -> error"_norm, error_centre, error_k3, [, "-> Call -> FIT_MATHIESON -> options"])
  CALL FIT_MATHIESON("-> Call -> FIT_MATHIESON -> reference", "-> Call -> FIT_MATHIESON -> distance", "-> Call -> FIT_MATHIESON -> norm", "-> Call -> FIT_MATHIESON -> centre", "-> Call -> FIT_MATHIESON -> k3", ...
       "-> Call -> FIT_MATHIESON -> error"_norm, error_centre, error_k3, [, "-> Call -> FIT_MATHIESON -> options"])
!W
Example: !W
  Call "-> Call -> book_histogram"(ref_m,50)
  Call "-> Call -> book_histogram"(ref_b,50)
  For i From 1 To 65 Do
     Call "-> Call -> get_histogram"(hist,`profile.hist`,"-> algebra -> functions -> 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 "-> Call -> fill_histogram"(ref_m,xc)
     Call "-> Call -> barycentre"(hist,b,5)
     Call "-> Call -> fill_histogram"(ref_b,b)
     Say "Centre:     {xc} +/- {exc}"
     Say "Barycentre: {b}"
     Say "K3:         {k3} +/- {ek3}"
  Enddo
  Call "-> Call -> plot_histogram"(ref_m,`Reconstructed x [cm]`,`Mathieson fits`)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_histogram"(ref_b,`Reconstructed x [cm]`,`Barycentre`)
  Call "-> Call -> plot_end"
!W
(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: !W
!W
[1] !W
J.S. Gordon & E. Mathieson, NIM 227 (1984) 267-276 !W
[2] !W
E. Mathieson & J.S. Gordon, NIM 227 (1984) 277-282 !W
[3] !W
E. Mathieson, NIM A270 Letter to the Editor (1988) 602-603 !W
!D3 JS Gordon & E Mathieson, NIM 227 (1984) 267-276 E Mathieson & JS Gordon, NIM 227 (1984) 277-282 E Mathieson, NIM A270 (1988) 602-603 3 reference Should contain on entry the "-> algebra -> variables -> types -> Histogram" which is to be fitted. The argument is not modified by the call. [Mandatory argument if the histogram format is used.] 3 x Should contain on entry a 1-dimensional "-> algebra -> variables -> types -> Matrix" in which the abscissa are stored of the points on which the fit is to be performed. This vector should have the same size as "-> Call -> FIT_GAUSSIAN -> y". The argument is not modified by the procedure. [Mandatory argument if the matrix format is used.] 3 y Should contain on entry a 1-dimensional "-> algebra -> variables -> types -> Matrix" in which the function values are stored of the points on which the fit is to be performed. This vector should have the same size as "-> Call -> FIT_GAUSSIAN -> x". The argument is not modified by the procedure. [Mandatory argument if the matrix format is used.] 3 err_y Should contain on entry the errors on the function values. These errors can either be specified in the form of a single "-> algebra -> variables -> types -> Number", which is interpreted as a common error for all function values, or in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix" of errors for each point separately. If a Matrix type argument is used, then it must have the same length as "-> Call -> FIT_GAUSSIAN -> x" and "-> Call -> FIT_GAUSSIAN -> y". The argument is not modified by the procedure. [Mandatory argument if the matrix format is used.] 3 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. 3 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. 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. 3 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 preferred value of K3. The argument is then not modified and the corresponding error is set to 0. 3 error The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. 3 options The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end 2 FIT_POLYA Fits a Polya distribution to an histogram or to 1-dimensional matrices. The Polya distribution is a special case of a \Γ-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 "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Format for histograms: !W
  CALL FIT_POLYA("-> Call -> FIT_POLYA -> reference", "-> Call -> FIT_POLYA -> factor", "-> Call -> FIT_POLYA -> offset", "-> Call -> FIT_POLYA -> slope", "-> Call -> FIT_POLYA -> \θ", ...
       "-> Call -> FIT_POLYA -> error"_factor, error_offset, error_slope, error_theta [, "-> Call -> FIT_POLYA -> options"])
!W
Format for matrices: !W
  CALL FIT_POLYA("-> Call -> FIT_POLYA -> x", "-> Call -> FIT_POLYA -> y", "-> Call -> FIT_POLYA -> err_y", "-> Call -> FIT_POLYA -> factor", "-> Call -> FIT_POLYA -> offset", "-> Call -> FIT_POLYA -> slope", "-> Call -> FIT_POLYA -> \θ", ...
       "-> Call -> FIT_POLYA -> error"_factor, error_offset, error_slope, error_theta [, "-> Call -> FIT_POLYA -> options"])
!W
Example: !W
  Call "-> Call -> book_histogram"(ref,100,0,10)
  For i From 1 To 2000 Do
     Call "-> 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}."
!W
(First we fill a histogram with a Polya distribution of which we know the \θ 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.) 3 reference The histogram is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or "-> Call -> GET_HISTOGRAM". This argument may also be an expression that results in a histogram. The argument is not modified on return. 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. 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. 3 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. 3 factor See "-> Call -> FIT_POLYA -> parameters". 3 offset See "-> Call -> FIT_POLYA -> parameters". 3 slope See "-> Call -> FIT_POLYA -> parameters". 3 \θ See "-> Call -> FIT_POLYA -> parameters". 3 parameters The function that is fitted to the data points is given by !W
  function = factor slope (\θ+1)\\θ+1\/\Γ(\θ+1) (offset+slope*x)\\θ\ e\-(\θ+1)*(offset+slope*x)\
!W
i.e. a Polya distribution with argument offset+slope*x and with Polya parameter \θ. 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. 3 error The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. 3 options The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitly provided in that case. 2. The plot is always made on a linear-logarithmic scale. !Wol_end 2 FIT_POLYNOMIAL Fits a polynomial to an histogram or to 1-dimensional matrices. In addition to the parameters, the global variable "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True is the fit converged, and False otherwise. Format for histograms: !W
  CALL FIT_POLYNOMIAL("-> Call -> FIT_POLYNOMIAL -> reference", "-> Call -> FIT_POLYNOMIAL -> a"0, a1, a2, ..., an, ...
       "-> Call -> FIT_POLYNOMIAL -> err_a"0, err_a1, err_a2, ..., err_an [, "-> Call -> FIT_POLYNOMIAL -> options"])
!W
Format for matrices: !W
  CALL FIT_POLYNOMIAL("-> Call -> FIT_POLYNOMIAL -> x", "-> Call -> FIT_POLYNOMIAL -> y", "-> Call -> FIT_POLYNOMIAL -> err_y", "-> Call -> FIT_POLYNOMIAL -> a"0, a1, a2, ..., an, ...
       "-> Call -> FIT_POLYNOMIAL -> err_a"0, err_a1, err_a2, ..., err_an [, "-> Call -> FIT_POLYNOMIAL -> options"])
!W
Example: !W
  Call hdelete(ref)
  Call hbook(ref,100,-2,2)
  For i From 1 To 10000 Do
     Global x=("-> algebra -> functions -> rnd_uniform"-0.5)*4 
     Global dy=0.01*("-> algebra -> functions -> 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}."
!W
This example is a test to verify that the fit works. In the procedure calls, HDELETE is short for "-> Call -> DELETE_HISTOGRAM", HBOOK for "-> Call -> BOOK_HISTOGRAM" and HFILL for "-> Call -> FILL_HISTOGRAM". 3 reference The histogram is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or "-> Call -> GET_HISTOGRAM". This argument may also be an expression that results in a histogram. The argument is not modified on return. 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. 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. 3 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. 3 a Terms in the polynomial expansion: !W
  polynomial = a\0\ + a\1\*x + a\2\*x\2\ + a\3\*x\3\ + ... + a\n\*x\n\
!W
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. 3 err_a The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to: !W
  \√(\χ\²/(#points - #parameters))
!W
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. 3 options The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commata. Additional text may be added - no error message will be issued if unrecognised keywords are used. !Wtable_start !T+P + + . -------------------------------------------------------------- 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 -------------------------------------------------------------- !Wtable_end Note: the EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitly provided in that case. 2 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: !W
  CALL FORCE_FIELD(x, y, ex, ey)
!W
3 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: !W
  for x: log(r)
  for y: \φ, in radians
!W
3 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: !W
  Er = Ex/r
  Ephi = Ey/r
!W
2 GAS_AVAILABILITY Returns the status of the gas data. Format: !W
  CALL GAS_AVAILABILITY("-> Call -> GAS_AVAILABILITY -> object", "-> Call -> GAS_AVAILABILITY -> available")
!W
3 object A "-> algebra -> variables -> types -> String" that describes the quantity of which you wish to know whether it is available. Can be any of the following: !Wtable_start !T+P R . ------------------------------------------------------------- Object GASOK bit ------------------------------------------------------------- ATTACHMENT-COEFFICIENT 6 CLUSTERING-DATA 5 DIFFUSION-TENSOR 11 DRIFT-VELOCITY or VELOCITY-E 1 ION-DISSOCIATION-COEFFICIENT 12 ION-MOBILITY 2 LONGITUDINAL-DIFFUSION-COEFFICIENT 3 LORENTZ-ANGLE 7 TOWNSEND-COEFFICIENT 4 TRANSVERSE-DIFFUSION-COEFFICIENT 8 VELOCITY-BTRANSVERSE 9 VELOCITY-E or DRIFT-VELOCITY 1 VELOCITY-EXB 10 ------------------------------------------------------------- !Wtable_end 3 available Is, on return, a "-> algebra -> variables -> types -> Logical" which is set to True or False depending on whether the object is available or not. 2 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 identifier. All arguments are optional. Format: !W
  CALL GET_CELL_DATA(["-> Call -> GET_CELL_DATA -> number_of_wires" [, "-> Call -> GET_CELL_DATA -> cell_type" [, ...
       "-> Call -> GET_CELL_DATA -> coordinates" [, "-> Call -> GET_CELL_DATA -> identifier"]]]])
!W
3 number_of_wires Is set to the "-> algebra -> variables -> types -> Number" of wires present in the chamber. 3 cell_type Is, on return, a "-> algebra -> variables -> types -> String" which describes the "-> &CELL -> methods -> potential_function" which is used to compute the field in the chamber. 3 coordinates Is, on return, a "-> algebra -> variables -> types -> String" which explains the "-> &CELL -> methods -> coordinate_system" used in the chamber. Three values can be returned, "-> &CELL -> methods -> coordinate_system -> Cartesian", "-> &CELL -> methods -> coordinate_system -> Polar" and "-> &CELL -> methods -> coordinate_system -> Tube". 3 identifier Is, on return, a "-> algebra -> variables -> types -> String" which contains the identifier that you may have assigned to the chamber with the "-> &CELL -> CELL-IDENTIFIER" command. 2 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 "-> Call -> INTERNAL_TO_CARTESIAN" and "-> Call -> 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: !W
  CALL GET_CELL_SIZE(xmin, ymin, zmin, xmax, ymax, zmax)
  CALL GET_CELL_SIZE(xmin, ymin, xmax, ymax)
!W
Example: see "-> Call -> GET_WIRE_DATA" 2 GET_CLUSTER Once the "-> &DRIFT -> TRACK" has been set and cluster generation initialised by means of a call to "-> Call -> NEW_TRACK", one can repeatedly call GET_CLUSTER to get one cluster at the time. A flag, "-> Call -> GET_CLUSTER -> done", is set when all clusters for the track have been generated. In addition to the parameters, the global variable "-> algebra -> variables -> predefined -> OK" is set by this procedure. Its value is True if generating the clusters worked properly, otherwise it will be set to False. OK is set to False if the done flag has been set to True. Before using the cluster location and energy, the value of the done argument and of the OK global variable should be checked. The parameters should not be used if either of these two has been set to True. Format: !W
  CALL GET_CLUSTER("-> Call -> GET_CLUSTER -> xcls", "-> Call -> GET_CLUSTER -> ycls", "-> Call -> GET_CLUSTER -> zcls", "-> Call -> GET_CLUSTER -> npair", "-> Call -> GET_CLUSTER -> ecls", ["-> Call -> GET_CLUSTER -> extra"1,] "-> Call -> GET_CLUSTER -> done")
!W
Example: !W
  "-> &DRIFT -> track" 0 1 1 1 muon energy 10000 nodelta
  Call "-> Call -> book_histogram"(size,100)
  For i From 1 To 100 Do
     Call "-> Call -> new_track"
     Until done Do
        Call get_cluster(xcls,ycls,zcls,npair,ecls,done)
        If done Then Iterate
        Call "-> Call -> fill_histogram"(size,npair)
     Enddo
  Enddo
  !"-> graphics -> options" log-y
  Call "-> Call -> plot_histogram"(size,`Cluster size`,...
     `Cluster size distribution`)
  Call "-> Call -> plot_end"
!W
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 \δ-electrons (they usually have a very short range), we use the NO"-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" option on the "-> &DRIFT -> TRACK" command. This compresses the \δ-electrons into clusters. 3 xcls See "-> Call -> GET_CLUSTER -> coordinates". 3 ycls See "-> Call -> GET_CLUSTER -> coordinates". 3 zcls See "-> Call -> GET_CLUSTER -> coordinates". 3 coordinates Contains on return the coordinates at which the cluster is produced. The cluster location is returned in "-> &CELL -> methods -> coordinate_system -> Cartesian" coordinates, also if the cell has been entered in "-> &CELL -> methods -> coordinate_system -> Polar" coordinates. The "-> Call -> INTERNAL_TO_POLAR" procedure can be used for the conversion. These arguments should not be used if "-> Call -> GET_CLUSTER -> done" has been set to True or "-> algebra -> variables -> predefined -> OK" to False. This 3 arguments should be a simple global variables, not formulae 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 "-> algebra -> variables -> types -> Number"s with unit cm, no matter the coordinate system that is used. 3 ecls Contains on return the energy in MeV deposited in the cluster. This argument should not be used if "-> Call -> GET_CLUSTER -> done" has been set to True or "-> algebra -> variables -> predefined -> OK" to False. The precise interpretation of the energy that is returned depends on the clustering model that is in effect: !Wul_start - If you use "-> &DRIFT -> TRACK -> Heed" to generate clusters and enable the "-> &DRIFT -> TRACK -> HEED -> DELTA-ELECTRONS" option, then each "cluster" is in fact a single electron and the argument will on return contain the energy deposited in that electron. - If you use Heed but disable the DELTA-ELECTRONS option, then the energy of the virtual \γ that produced the \δ-electron will be returned, without subtraction of the binding energy of the electron. Thus, the total energy for a track, will be larger with NODELTA-ELECTRONS than with DELTA-ELECTRONS. - 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. - When using "-> &DRIFT -> TRACK -> SRIM" to generate clusters, the energy deposited in a cluster is by construction constant, up to fluctuations, and these clusters bear no physical relation to the ionisation deposited by a single virtual photon. The energy of each such cluster is set equal to the energy loss that has been generated over the step. This energy has served as basis to compute the cluster size, by dividing it by the "-> &GAS -> SRIM -> work" function. - Otherwise, the energy will as a rule be set to 0. !Wul_end 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 argument is of type "-> algebra -> variables -> types -> Number" after the call. 3 npair Contains on return the "-> algebra -> variables -> types -> Number" of electrons (and ions) present in the cluster. This argument should not be used if "-> Call -> GET_CLUSTER -> done" has been set to True or "-> algebra -> variables -> predefined -> 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. 3 extra Contains on return additional information. The actual contents varies with the clustering model. !Wul_start - "-> &DRIFT -> TRACK -> SRIM" clustering: kinetic energy of the ion, expressed in MeV; - "-> &DRIFT -> TRACK -> TRIM" clustering: kinetic energy of the ion, expressed in MeV; - "-> &DRIFT -> TRACK -> HEED" clustering with \δ-electrons enabled: pointer to the ancestor \δ-electron; - all other cases: set to 0. !Wul_end This argument is optional. If it is present, then it must be the one-but-last argument of the procedure. That is, if 6 arguments are passed, then the 6th will be considered to be "-> Call -> GET_CLUSTER -> done" and extra will not be returned. 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. 3 done This argument is set to False if a cluster has been generated successfully. It is set to True if the present call didn't result in a cluster because: !Wul_start - the specified number of clusters has been generated already, - the particle has reached the end point of the track, - it has stopped after losing all its energy. !Wul_end Further calls will not result in clusters either. 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. 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. 2 GET_DRIFT_LINE Returns the (x,y,z,t) coordinates of the current drift-line. Each of the 4 arguments receives a 1-dimensional "-> algebra -> variables -> types -> 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 "-> Call -> DRIFT_INFORMATION" provides easier access to the information. The drift time is expressed in \μsec 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: !W
  (\ρ,\φ)=(log(\√(x\²+y\²),arctan(y/x))
!W
These can be converted to Cartesian or polar coordinates with the "-> Call -> INTERNAL_TO_CARTESIAN" and "-> Call -> INTERNAL_TO_POLAR" procedures. Format: !W
  CALL GET_DRIFT_LINE(x [, y [, z [, t]]])
!W
Example: !W
  "-> Say" "Please enter (x,y) of the starting point"
  "-> Parse" Terminal x_start y_start
  Call "-> Call -> drift_electron"(1,1,status,time)
  Call get_drift_line(x,y,z,t)
  Call "-> Call -> plot_graph"(t,x,`Time [microsec]`,`x [cm]`,`x vs time`)
  Call "-> Call -> plot_comment"(`UP-LEFT`,`Status: `/status)
  Call plot_comment(`DOWN-LEFT`,`Drift time: `/"-> algebra -> functions -> string"(time)/` [microsec]`)
  Call plot_comment(`UP-RIGHT`, `From (x,y)=(`/string(x_start)/`,`/...
     string(y_start)/`)`)
  Call "-> Call -> plot_end"
!W
A way to plot the relation between the x-coordinate of a drift line and the drift time. 2 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 "-> Call -> 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 "-> algebra -> variables -> types -> Matrix". Any value this argument has before the procedure call, is lost after the call. Format: !W
  CALL GET_E/P_TABLE(ep)
!W
Example: !W
  Call get_e/p_table(ep)
  Call "-> Call -> get_gas_data"(p)
  Call "-> Call -> townsend"(ep*p,0,0,a)
  Call "-> Call -> plot_graph"(ep*p,a,`E [V/cm]`,`α [1/cm]`, ...
     `Townsend coefficient`)
  Call "-> Call -> plot_error_bar"(ep*p,a,0,0.1*a)
  Call "-> Call -> plot_end"
!W
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. 2 GET_GAS_DATA Returns the pressure, temperature and identifier of the gas. Format: !W
  CALL GET_GAS_DATA("-> Call -> GET_GAS_DATA -> pressure" [, "-> Call -> GET_GAS_DATA -> temperature" [, "-> Call -> GET_GAS_DATA -> identifier"]])
!W
Example: !W
  Call get_gas_data(p, t, gasid)
  Say "Gas identifier is {gasid}."
!W
3 pressure Contains on return the pressure of the gas in Torr. The pressure of the gas is established with the "-> &GAS -> PRESSURE" command. This value of this argument on entry is not used, and is lost after the procedure has completed. On return, this argument is of type "-> algebra -> variables -> types -> Number". 3 temperature Contains on return the temperature of the gas in K. The temperature of the gas is established with the "-> &GAS -> TEMPERATURE" command. This value of this argument on entry is not used, and is lost after the procedure has completed. On return, this argument is of type "-> algebra -> variables -> types -> Number". This argument is optional. 3 identifier Contains on return the identifier of the gas as set with the "-> &GAS -> GAS-IDENTIFIER" statement or (implicitly) by the "-> &GAS -> MAGBOLTZ" command. This value of this argument on entry is not used, and is lost after the procedure has completed. On return, this argument is of type "-> algebra -> variables -> types -> String". This argument is optional. 2 GET_HISTOGRAM Retrieves an "-> algebra -> variables -> types -> Histogram" which has been written to disk by "-> Call -> WRITE_HISTOGRAM". After retrieval, the histogram can further be filled etc. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the histogram has successfully been retrieved and to False if a problem occurred. Format: !W
  CALL GET_HISTOGRAM("-> Call -> GET_HISTOGRAM -> reference", "-> Call -> GET_HISTOGRAM -> file" [, "-> Call -> GET_HISTOGRAM -> member"])
!W
3 reference This is the name by which you want to reference the histogram when performing fits on it (e.g. with a call to "-> Call -> FIT_GAUSSIAN") and when performing arithmetic on it. This argument plays the same role as the "-> Call -> BOOK_HISTOGRAM -> reference" argument of "-> Call -> 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. 3 file The name of the Garfield "-> dataset -> structure -> file" from which the histogram should be read. This argument should be of type "-> algebra -> variables -> types -> String". 3 member The name that has been given to the "-> dataset -> structure -> 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. This argument should be of type "-> algebra -> variables -> types -> String". 2 GET_MATRIX GET_MATRIX is used to recover a "-> algebra -> variables -> types -> Matrix" from a disk file to which it has been written with the "-> Call -> WRITE_MATRIX" procedure. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the matrix is successfully retrieved, and to False in case of a problem. Format: !W
  CALL GET_MATRIX("-> Call -> GET_MATRIX -> matrix", "-> Call -> GET_MATRIX -> file" [, "-> Call -> GET_MATRIX -> member"])
!W
Example: See "-> Call -> WRITE_MATRIX". 3 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. 3 file The name of the Garfield "-> dataset -> structure -> file" from which the matrix is to be read. This argument should be of type "-> algebra -> variables -> types -> String". 3 member The name of the "-> dataset -> structure -> 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. This argument should be of type "-> algebra -> variables -> types -> String". 2 GET_PERIODS Returns information concerning the periodicities of the chamber. Format: !W
  CALL GET_PERIODS("-> Call -> GET_PERIODS -> yesno"_x, "-> Call -> GET_PERIODS -> length"_x, yesno_y, length_y)
!W
3 yesno "-> algebra -> variables -> types -> Logical"s that are set to True if the corresponding periodicity is present in the cell and to False otherwise. 3 length "-> algebra -> variables -> types -> Number"s that are set to the length of one period, if existing. Internal coordinates are used if the cell has been described in polar coordinates, 2 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. Raw signals are obtained by computing drift trajectories, and multiplying at each step, the local velocity with the weighting field. Raw signals do not, as a rule, have equal time intervals. Use the "-> Call -> LIST_RAW_SIGNALS" procedure to find out which raw signals currently are in memory. Format: !W
  CALL GET_RAW_SIGNAL("-> Call -> GET_RAW_SIGNAL -> type", "-> Call -> GET_RAW_SIGNAL -> electrode", "-> Call -> GET_RAW_SIGNAL -> avalanche_wire", "-> Call -> GET_RAW_SIGNAL -> angle", ...
       "-> Call -> GET_RAW_SIGNAL -> time", "-> Call -> GET_RAW_SIGNAL -> signal")
!W
3 type Should be a "-> algebra -> variables -> types -> String" that contains either `ELECTRON` or `ION`, for respectively electron and ion induced currents. 3 electrode This is the "-> algebra -> variables -> types -> 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed. [No default, this is a mandatory parameter.] 3 avalanche_wire This is the wire "-> algebra -> variables -> types -> Number", as shown in the print-out generated in response to the "-> &CELL -> OPTIONS -> CELL-PRINT" option and the "-> &OPTIMISE -> PRINT-CELL" command, 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. 3 angle The incidence angle in radians of the electron or the ion. This argument should be a "-> algebra -> variables -> types -> Number". 3 time On return, this argument is a 1-dimensional "-> algebra -> variables -> types -> Matrix" that contains the sampling points in \μsec 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. 3 signal Contains, on return, the signal in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". Signal currents are expressed in \μA 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. 2 GET_SIGNAL Copies a signal to a (set of) 1-dimensional matrices. Format: !W
  CALL GET_SIGNAL("-> Call -> GET_SIGNAL -> electrode", "-> Call -> GET_SIGNAL -> time", "-> Call -> GET_SIGNAL -> direct" [, "-> Call -> GET_SIGNAL -> cross"])
!W
Example: 3 electrode This is the "-> algebra -> variables -> types -> 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed. [No default, this is a mandatory parameter.] 3 time On return, this argument is a 1-dimensional "-> algebra -> variables -> types -> Matrix" that contains the sampling points in \μsec 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. 3 direct Contains, on return, the direct component of the signal in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". Signals are expressed in \μA 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. 3 cross Contains, on return, the cross induced component of the signal in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". This argument is optional. Signals are expressed in \μA 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. 2 GET_SOLID_DATA Returns information about a solid. Format: !W
  CALL GET_SOLID_DATA(solid, qsolid)
!W
Example: see "-> Call -> INTEGRATE_CHARGE". 3 solid Number of the solid. Solids are numbered sequentially, starting from 1. 3 qsolid The sum of all charge applied by neBEM to surface panels of the solid so as to satisfy the boundary conditions. The charge is expressed in units of V.cm and thus needs to be multiplied by 4\π\ε\0\ for conversion to Coulomb. See the example. 2 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 "-> Call -> INTERNAL_TO_POLAR" procedure to convert to, for instance, polar coordinates. All arguments are mandatory. Format: !W
  CALL GET_X_PLANE_DATA(yn_1, x_1, V_1, label_1, ...
                        yn_2, x_2, V_2, label_2)
!W
Example: !W
  Call "-> 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={"-> algebra -> functions -> exp"(x1)} and with V={V1}."
     If yn2 Then Say "There is a plane at r={"-> algebra -> functions -> 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
!W
2 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 "-> Call -> INTERNAL_TO_POLAR" procedure to convert to polar coordinates. All arguments are mandatory. Format: !W
  CALL GET_Y_PLANE_DATA(yn_1, y_1, V_1, label1, ...
                        yn_2, y_2, V_2, label2)
!W
Example: !W
  Call "-> 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
!W
2 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: !W
  CALL GET_WIRE_DATA("-> Call -> GET_WIRE_DATA -> wire" [, "-> Call -> GET_WIRE_DATA -> x" [, "-> Call -> GET_WIRE_DATA -> y" [, "-> Call -> GET_WIRE_DATA -> V" [, "-> Call -> GET_WIRE_DATA -> d" [, "-> Call -> GET_WIRE_DATA -> q" [, "-> Call -> GET_WIRE_DATA -> label" [, ...
     "-> Call -> GET_WIRE_DATA -> length" [, "-> Call -> GET_WIRE_DATA -> weight" [, "-> Call -> GET_WIRE_DATA -> density"]]]]]]]]])
!W
Example: !W
  Call "-> 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
!W
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. 3 wire Should contain, on input, the "-> algebra -> variables -> types -> Number" of the wire about which information is desired. Wire numbers can be obtained from the listing produced in response to the "-> &CELL -> OPTIONS -> CELL-PRINT" option in the cell section and also by the "-> &OPTIMISE -> PRINT-CELL" command in the optimisation section. This argument is mandatory and is not modified. [No default.] 3 x Contains, on return, the x- or \ρ-location of the wire in cm for x, and log(cm) for \ρ. 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 "-> Call -> INTERNAL_TO_CARTESIAN" and "-> Call -> 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 y Contains, on return, the y- or \φ-location of the wire in cm for y, and in radians for \φ. 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 "-> Call -> INTERNAL_TO_CARTESIAN" and "-> Call -> 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 d Contains, on return, the diameter 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 V Contains, on return, the potential at the wire surface as entered with the "-> &CELL -> ROWS" statement in the "-> &CELL" section. The potential is returned in Volts. The "-> &FIELD -> 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 q Contains, on return, the charge in V that has been computed for the wire. Internally, Garfield expresses charges in units of V to avoid scaling factors. Also the "-> Call -> INTEGRATE_CHARGE" procedure returns charges in V. It is, however, more usual to express wire charges in pC/cm, as is for instance done by the "-> &CELL -> OPTIONS -> CELL-PRINT" option. To convert from V to C/cm, multiply by 2\π\ε\0\, approximately 5.56\ 10\-13\\ C/V.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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 label Contains, on return, a character "-> algebra -> variables -> types -> 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. 3 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 3 density Contains, on return, the density of the material of which the wire is made, in g/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. The argument will be of type "-> algebra -> variables -> types -> Number" on return. 2 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: !W
  CALL GKS_AREA(x,y)
!W
3 coordinates The arguments of this procedure are 1-dimensional vectors (i.e. of type "-> algebra -> variables -> types -> Matrix") of equal length. The vectors should have a minimum length of 3. [No defaults, these are mandatory parameters.] 2 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: !W
  CALL GKS_POLYLINE(x,y)
!W
3 coordinates The arguments of this procedure are 1-dimensional vectors (i.e. of type "-> algebra -> variables -> types -> Matrix") of equal length. The vectors should have a minimum length of 2. [No defaults, these are mandatory parameters.] 2 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: !W
  CALL GKS_POLYMARKER(x,y)
!W
3 coordinates The arguments of this procedure are 1-dimensional vectors (i.e. of type "-> algebra -> variables -> types -> Matrix") of equal length. The vectors should have a minimum length of 1. [No defaults, these are mandatory parameters.] 2 GKS_SELECT_NT Selects the normalisation transformation. This procedure is equivalent to the GKS routine GSELNT. Format: !W
  CALL GKS_SELECT_NT("-> Call -> GKS_SELECT_NT -> nt")
!W
Example: See "-> Call -> PLOT_START". 3 nt The "-> algebra -> variables -> types -> 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.] 2 GKS_SET_CHARACTER_EXPANSION Sets the character expansion factor. This procedure is an interface to the GKS routine GSCHXP. Format: !W
  CALL GKS_SET_CHARACTER_EXPANSION(expansion)
!W
3 expansion A "-> algebra -> variables -> types -> 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. 2 GKS_SET_CHARACTER_HEIGHT Sets the character height This procedure is an interface to the GKS routine GSCHH. Format: !W
  CALL GKS_SET_CHARACTER_HEIGHT(height)
!W
2 GKS_SET_CHARACTER_SPACING Sets the character spacing This procedure is an interface to the GKS routine GSCHSP. Format: !W
  CALL GKS_SET_CHARACTER_SPACING("-> Call -> GKS_SET_CHARACTER_SPACING -> spacing")
!W
3 spacing A "-> algebra -> variables -> types -> Number" which is used to increase the spacing between the letters of a piece of text. A spacing of 0 corresponds to normal text. 2 GKS_SET_CHARACTER_UP_VECTOR Sets the character up vector This procedure is an interface to the GKS routine GSCHUP. Format: !W
  CALL GKS_SET_CHARACTER_UP_VECTOR(x, y)
!W
3 vector A set of 2 "-> algebra -> variables -> types -> Number"s that form a vector perpendicular to the path of the text while the text flows from left to right when looking along the vector. 2 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: !W
  CALL GKS_SET_TEXT_ALIGNMENT(hor, vert)
!W
3 alignments The horizontal and vertical alignments are "-> algebra -> variables -> types -> String"s which can have the following values: !Wtable_start !T+P R + + . ------------------------------------------------------ Alignment Numeric Meaning Notes ------------------------------------------------------ NORMAL 0 Depends on system Usually LEFT LEFT 1 Left aligned - CENTRE 2 Centre aligned - RIGHT 3 Right aligned - ------------------------------------------------------ !Wtable_end and v one of the vert !Wtable_start !T+P R + + . ------------------------------------------------------ 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 ------------------------------------------------------ !Wtable_end [No defaults, these are mandatory arguments.] 2 GKS_SET_TEXT_COLOUR Sets the text colour index. This procedure is a direct interface to the GKS routine GSTXCI. Format: !W
  CALL GKS_SET_TEXT_COLOUR("-> Call -> GKS_SET_TEXT_COLOUR -> colour")
!W
3 colour The colour is specified with a "-> algebra -> variables -> types -> String" that contains the name of the colour. Colour names are established with the "-> graphics -> COLOUR" command. 2 GKS_SET_TEXT_FONT_PRECISION Sets the text font and precision. This procedure is a direct interface to the GKS routine GSTXFP. !W
  CALL GKS_SET_TEXT_FONT_PRECISION("-> Call -> GKS_SET_TEXT_FONT_PRECISION -> font", "-> Call -> GKS_SET_TEXT_FONT_PRECISION -> precision")
!W
3 font The "-> algebra -> variables -> types -> Number" of the HIGZ "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> HIGZ -> fonts" or of the GTS-GRAL/GKS "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> GTS-GRAL -> fonts" that you wish to use. 3 precision A "-> algebra -> variables -> types -> Number" with one of the text precisions in GKS: !Wtable_start !T+P R . ------------------------------------------------------ Precision Meaning ------------------------------------------------------ STROKE Highest precision, all attributes respected CHARACTER Standard precision STRING Low precision, suited for fast rendering ------------------------------------------------------ !Wtable_end 2 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 "-> Call -> GKS_SET_CHARACTER_EXPANSION", "-> Call -> GKS_SET_CHARACTER_HEIGHT", "-> Call -> GKS_SET_CHARACTER_SPACING", "-> Call -> GKS_SET_CHARACTER_UP_VECTOR", "-> Call -> GKS_SET_TEXT_ALIGNMENT", "-> Call -> GKS_SET_TEXT_COLOUR" and "-> Call -> GKS_SET_TEXT_FONT_PRECISION", or at the Garfield level by calling "-> Call -> SET_TEXT_ATTRIBUTES". Format: !W
  CALL GKS_TEXT(x,y,"-> Call -> GKS_TEXT -> text")
!W
3 coordinates The arguments of this procedure are 2 "-> algebra -> variables -> types -> Number"s 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.] 3 text A text "-> algebra -> variables -> types -> String". [No default, this is a mandatory parameter.] 2 GKS_VIEWPORT Sets the viewport for a normalisation transformation. This procedure is provided for completeness only - for most applications, the "-> graphics -> VIEWPORT" graphics command will prove more convenient. Specifying a viewport doesn't entail an automatic change of normalisation transformation. For this, one needs to call the "-> Call -> GKS_SELECT_NT" procedure. A call to a procedure like "-> Call -> PLOT_FRAME" overrides the viewport setting for normalisation transformation number 1 with the parameters that can be set with the VIEWPORT graphics command. Also, all regular Garfield plots will modify these viewport settings. This procedure is equivalent to the GKS routine GSVP. Format: !W
  CALL GKS_VIEWPORT("-> Call -> GKS_VIEWPORT -> nt", xmin, xmax, ymin, ymax)
!W
Example: See "-> Call -> PLOT_START". 3 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.] 3 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.] 2 GKS_WINDOW Sets the window for a normalisation transformation. This procedure is provided for completeness only - for most applications, the "-> Call -> PLOT_FRAME" procedure together with the "-> graphics -> VIEWPORT" graphics command will prove more convenient. Specifying a window doesn't entail an automatic change of normalisation transformation. For this, one needs to call the "-> Call -> GKS_SELECT_NT" procedure. A call to a procedure like PLOT_FRAME overrides the window setting for normalisation transformation number 1 with the dimensions specified in the argument. Also all regular Garfield plots will modify these window settings. This procedure is equivalent to the GKS routine GSWN. Format: !W
  CALL GKS_WINDOW(nt, xmin, xmax, ymin, ymax)
!W
Example: See "-> Call -> PLOT_START". 3 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.] 3 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.] 2 HISTOGRAM_TO_MATRIX Makes a "-> algebra -> variables -> types -> Matrix" copy of an "-> algebra -> variables -> types -> Histogram", optionally returning the range of the histogram in the form of a pair of "-> algebra -> variables -> types -> Number"s. The histogram is not affected by this operation. Format: !W
  CALL HISTOGRAM_TO_MATRIX(hist, matrix [, min [, max]])
!W
Example: !W
  Call "-> Call -> book_histogram"(ref1,10,0,1)
  For i From 1 To 1000 Do
     Call "-> Call -> fill_histogram"(ref1,"-> algebra -> functions -> rnd_uniform")
  Enddo
  Call "-> Call -> plot_histogram"(ref1)
  Call "-> Call -> plot_end"
  Call histogram_to_matrix(ref1,a,min,max)
  Call matrix_to_histogram(a,min,max,ref2)
  Call "-> Call -> plot_histogram"(ref2)
  Call "-> Call -> plot_end"
!W
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. 2 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 pure signals with the "-> &SIGNAL -> SIGNAL" command or with the "-> Call -> ADD_SIGNALS" procedure, process them (e.g. with "-> &SIGNAL -> CONVOLUTE-SIGNALS"), recuperate the electronics output with "-> Call -> GET_SIGNAL" and integrate the signal using the "-> algebra -> functions -> SUM" function. 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. Format: !W
  CALL INDUCED_CHARGE(x, y, z, "-> Call -> INDUCED_CHARGE -> particle", "-> Call -> INDUCED_CHARGE -> electrode" ...
     [, tmin, tmax], "-> Call -> INDUCED_CHARGE -> q")
!W
Example: !W
  &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}"
!W
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://cern.ch/garfield/examples/charge 3 particle A string that specifies the particle that you wish to drift. !Wtable_start !T+P + . -------------------------------- Value Meaning -------------------------------- `E-` electron `E+` positron `ION-` negatively charged ion `ION+` positively charged ion -------------------------------- !Wtable_end [No default, this is a mandatory parameter.] 3 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed. [No default, this is a mandatory parameter.] 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. 3 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. 2 INITIALISE_GENERATORS Calls all random number generators the specified number of times. This procedure is used to control the starting point in the random number generator sequences. By default, the random number generators are, at the start of the calculations, called a number of times that depends on the time of the day (product of the hours, minutes and seconds). If reproducible, yet different, sequences are required, then specify the -noRNDM_initialisation command line option and use this procedure to set a starting point. Format: !W
  CALL INITIALISE_GENERATORS(ncalls)
!W
Example: !W
  garfield -noRNDM_init
  (start)
  Call initialise_generators(1234)
!W
2 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 in a given library, then you should use "-> Call -> INQUIRE_MEMBER". The "-> algebra -> functions -> EXIST" function performs the same tasks as this procedure. Format: !W
  CALL INQUIRE_FILE("-> Call -> INQUIRE_FILE -> file", "-> Call -> INQUIRE_FILE -> exists")
!W
Example: !W
  "-> &CELL"
  Call inquire_file(`new_cell`,exist)
  If exist Then
     % "-> dataset -> delete" "dc1.lib" cell
     < new_cell
     "-> &CELL -> write" "dc1.lib" cell
  Else
     "-> &CELL -> get" "dc1.lib" cell
  Endif
!W
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. 3 file The name of the "-> dataset -> structure -> file" to be searched for. This parameter should be a "-> algebra -> variables -> types -> String" or an expression that evaluates to a character string. [This argument is mandatory, no default is supplied.] 3 exists Is set, on return, to a "-> algebra -> variables -> types -> Logical" which tells whether the file 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.] 2 INQUIRE_HISTOGRAM Returns information, such as the bin width and the range, about an histogram. Calling this procedure does not interfere with the filling process. The first 2 arguments are mandatory, the rest is optional. Format: !W
  CALL INQUIRE_HISTOGRAM("-> Call -> INQUIRE_HISTOGRAM -> reference", "-> Call -> INQUIRE_HISTOGRAM -> exists", "-> Call -> INQUIRE_HISTOGRAM -> set", "-> Call -> INQUIRE_HISTOGRAM -> channels", ...
       "-> Call -> INQUIRE_HISTOGRAM -> minimum", "-> Call -> INQUIRE_HISTOGRAM -> maximum", "-> Call -> INQUIRE_HISTOGRAM -> entries", "-> Call -> INQUIRE_HISTOGRAM -> mean", "-> Call -> INQUIRE_HISTOGRAM -> rms")
!W
3 reference The "-> algebra -> variables -> types -> Histogram" about which you wish to obtain information. [No default, this is a mandatory argument.] 3 exists Contains on return a "-> algebra -> variables -> types -> Logical" which has the value True if the histogram exists, and the value False if it doesn't. This argument is in practice always True since the first argument has to be a valid histogram "-> Call -> INQUIRE_HISTOGRAM -> reference". The argument's main application is in the area of debugging where it is used in conjunction with the "-> algebra -> functions -> REF_HISTOGRAM" function via which one can address directly the entire histogram storage area, also those parts for which no pointer in the form of a Global variable exists. 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. 3 set Contains on return a "-> algebra -> variables -> types -> Logical" which has the value True if the range of this histogram has been established, and False if this is an "-> Call -> BOOK_HISTOGRAM -> options -> 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. 3 channels Contains on return the "-> algebra -> variables -> types -> 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. 3 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 on return of type "-> algebra -> variables -> types -> Number". This is an optional argument. The value of this argument on entry is not used, and is lost after the procedure call. This number can also be obtained with the "-> algebra -> functions -> MINIMUM" function. 3 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 on return of type "-> algebra -> variables -> types -> Number". This is an optional argument. The value of this argument on entry is not used, and is lost after the procedure call. This number can also be obtained with the "-> algebra -> functions -> MAXIMUM" function. 3 entries Contains on return the "-> algebra -> variables -> types -> Number" of entries sofar collected in the histogram. The "-> Call -> FILL_HISTOGRAM -> 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. 3 mean 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 "-> Call -> FILL_HISTOGRAM -> 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 on return of type "-> algebra -> variables -> types -> Number". This is an optional argument. The value of this argument on entry is not used, and is lost after the procedure call. The mean of an histogram can also be obtained with the "-> algebra -> functions -> MEAN" function. 3 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 "-> Call -> FILL_HISTOGRAM -> 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 on return of type "-> algebra -> variables -> types -> Number". This is an optional argument. The value of this argument on entry is not used, and is lost after the procedure call. The RMS of an histogram can also be obtained with the "-> algebra -> functions -> RMS" function. 2 INQUIRE_MEMBER Tells whether a member in a library exists or not, approximately equivalent to the "-> dataset -> INDEX" dataset command. The "-> Call -> INQUIRE_MEMBER -> exists" argument is set to True only if all of the following conditions are fulfilled: !Wul_start - the file exists; - the file can be identified as a Garfield library; - the library contains the specified member; - the type of the member matches the type in the argument list. !Wul_end Otherwise "-> Call -> INQUIRE_MEMBER -> exists" is set to False and the arguments "-> Call -> INQUIRE_MEMBER -> member", "-> Call -> INQUIRE_MEMBER -> remark", "-> Call -> INQUIRE_MEMBER -> date" and "-> Call -> INQUIRE_MEMBER -> time" are not touched. Use the "-> Call -> INQUIRE_FILE" procedure if you only wish to find out whether a file exists. Format: !W
  CALL INQUIRE_MEMBER("-> Call -> INQUIRE_MEMBER -> file", "-> Call -> INQUIRE_MEMBER -> member", "-> Call -> INQUIRE_MEMBER -> type", "-> Call -> INQUIRE_MEMBER -> exists" ...
       [,"-> Call -> INQUIRE_MEMBER -> remark" [, "-> Call -> INQUIRE_MEMBER -> date" [, "-> Call -> INQUIRE_MEMBER -> time"]]])
!W
Example: !W
  "-> &GAS"
  Call inquire_member(`straw.gas`,`xe50e50`,`gas`,exist)
  If exist Then 
     "-> &GAS -> get" gas.dat xe50e50
  Else
     "-> &GAS -> pressure" 500
     "-> &GAS -> temperature" 300
     "-> &GAS -> magboltz" xenon 50 ethane 50
     "-> &GAS -> write" gas.dat xe50e50
  Endif
!W
In this example the existence of a member called XE50E50 in a library called straw.gas 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. 3 file The name of the "-> dataset -> structure -> file" in which the member is to be searched for. This parameter should be a "-> algebra -> variables -> types -> String" or an expression that evaluates to a character string. [This argument is mandatory, no default is supplied.] 3 member The name of the "-> dataset -> structure -> member" to be searched for. This parameter can be a wildcard, for instance `*` would search for the first occurrence 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 "-> algebra -> variables -> types -> String" or an expression that evaluates to a character string. Member names have a length of 8 at most. [This argument is mandatory, no default is supplied.] 3 type The "-> dataset -> structure -> type" of the member to be searched for. This argument can not be a wildcard. The argument should be a "-> algebra -> variables -> types -> 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.] 3 exists Is set, on return, to a "-> algebra -> variables -> types -> Logical" 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.] 3 remark This argument is set to the "-> dataset -> structure -> remark" "-> algebra -> variables -> types -> 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. [This is an optional argument.] 3 date This argument is set to the date on which the member was created. The date is returned as a "-> algebra -> variables -> types -> String" in the "dd/mm/yy" format. This argument should be modifiable, any object associated with it at the time the call is made, will be deleted. [This is an optional argument.] 3 time This argument is set to the time when the member was created. The time is returned as a "-> algebra -> variables -> types -> String" in the "hh.mm.ss" format. This argument should be modifiable, any object associated with it at the time the call is made, will be deleted. [This is an optional argument.] 2 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: `"-> algebra -> variables -> types -> String"`, `"-> algebra -> variables -> types -> Number"`, `"-> algebra -> variables -> types -> Logical"`, `"-> algebra -> variables -> types -> Histogram"`, `"-> algebra -> variables -> types -> Matrix"`, `"-> algebra -> variables -> types -> Undefined"` and `# Invalid`. This procedure provides a functionality which is similar to that of the "-> algebra -> functions -> TYPE" function. The main difference is that it is permissible to give the INQUIRE_TYPE procedure as first argument a variable that does not yet exist while this is not allowed with the TYPE function. The reason for this is that the arguments of procedures are automatically declared if they do not yet exist, while the arguments of functions must be existing variables. Format: !W
  CALL INQUIRE_TYPE(variable, type)
!W
Example: !W
  "-> Call" "-> Call -> book_histogram"(hist,10,0,10)
  Call inquire_type(hist,type)
  Say "Type is {type}"
!W
2 INTEGRATE_CHARGE Integrates, depending on the format that is used, the normal component of the electric field over !Wul_start - a circular area centred at (x,y) with radius r, or - a spherical area centred at (x,y,z) with radius r. !Wul_end By the Maxwell equations, this integral equals the charge contained inside the circle or sphere. Line charges are returned in units of V and point charges in units of V.cm. The reason for these unusual charge units is that Garfield uses potential functions without scaling factors that cancel between the charge and field calculations. The potential function used for line charges reads: !W
  V = q log(x\² + y\²)
!W
The procedure applied to a 2-dimensional area surrounding such a line charge, and no other charges, should return the value q. Charges expressed in V need to be scaled, as illustrated in the example, before the charge can be compared with the values shown by the "-> &CELL -> OPTIONS -> CELL-PRINT" option, which uses the pC/cm unit. "-> Call -> GET_WIRE_DATA" returns charges expressed in V, which can be compared directly. Similarly, in the 3-dimensional case, integrating the a point charge over a field with potential function !W
          _____________ -1
  V = q \\/ x\² + y\² + z\² 
!W
should yield a charge of q. To convert from V.cm to C, one should multiply with 4\π\ε\0\. Integration is performed using 6-point Gaussian quadrature over 50\ equal intervals for the 2-dimensional case, and over 20\ equal intervals both in \φ and in \θ for the 3-dimensional case. ANSYS field calculations are unit-independent when only voltage and periodicity boundary conditions are used. But a choice of distance unit needs to be made when charges are added because of the presence of \ε\0\ in the expressions for potentials and fields. When the ANSYS model is prepared in the native distance unit of metre, no precautions need to be taken. For all other distance units, the charge needs to be adjusted as explained in the "-> &OPTIMISE -> FIELD-MAP -> space_charge" example. Format: !W
  CALL INTEGRATE_CHARGE(x, y, [z,] r, q)
!W
Example 1: Verify the line and point charges. !W
  "-> &CELL"
  "-> &CELL -> rows"
  s * * 1 1 1000      // Wire 1
  s * * -1 -1 -1000   // Wire 2

  "-> &CELL -> options" "-> &CELL -> options -> cell-print"

  "-> &OPTIMISE"
  "-> &OPTIMISE -> charges"
  2 2 2 1
  3 2 3 4.5

  "-> &FIELD"
  Call integrate_charge(1.1, 0.5, 0.8, q)  // Integrate around wire 1
  "-> Global" eps0=8.854187817e-14              // Vacuum dielectric constant [C/V.cm]
  Call "-> Call -> get_wire_data"(1,xw,yw,vw,dw,ew)     // Retrieve internal wire charge
  Say "Charge on wire 1:"
  Say "    as calculated by integrate_charge:           {q} V,"
  Say "    should be equal to the get_wire_data charge: {ew} V,"
  Say "    the cell-print option should give:           {2*pi*eps0*q * 1e12} pC/cm."
  Call integrate_charge(5, 2, 2.5, 3.5, q)
  Say "Both point charges:"
  Say "    as calculated by integrate_charge:           {q} V.cm"
  Say "    in conventional units:                       {4*pi*eps0*q * 1e12} pC"
!W
Example 2: Verify solid charges as computed by neBEM !W
  "-> &CELL"
  "-> &CELL -> solids"
  "-> &CELL -> solids -> box"  centre        0        0        -1 ...
       half-lengths  0.01    0.01    0.01 ...
       voltage       1000 ...
       label a
  "-> &CELL -> solids -> box"  centre        0        0        +1 ...
       half-lengths  0.01    0.01    0.01 ...
       voltage       -1000 ...
       label b

  "-> &CELL -> options" "-> &CELL -> options -> cell-print"

  "-> &FIELD"
  "-> &FIELD -> track" 0 0 -1.1 0 0 1.1
  "-> &FIELD -> plot-field" graph v

  Call "-> Call -> integrate_charge"(0, 0, -1, 0.3, q1)  // Integrate around box 1
  Call "-> Call -> integrate_charge"(0, 0, +1, 0.3, q2)  // Integrate around box 2
  Call "-> Call -> get_solid_data"(1, qbox1)             // Obtain charge of box 1 from neBEM
  Call "-> Call -> get_solid_data"(2, qbox2)             // Obtain charge of box 2 from neBEM

  "-> Global" eps0=8.854187817e-14               // Vacuum dielectric constant [C/V.cm]
  Say "Charge on first box:"
  Say "    as calculated by integrate_charge:            {q1} V.cm,"
  Say "    should be equal to the get_solid_data charge: {qbox1} V.cm,"
  Say "    the cell-print option should show:            {q1 * 4*pi*eps0 * 1e12} pC."
  Say "Charge on second box:"
  Say "    as calculated by integrate_charge:            {q2} V.cm,"
  Say "    should be equal to the get_solid_data charge: {qbox2} V.cm,"
  Say "    the cell-print option should show:            {q2 * 4*pi*eps0 * 1e12} pC."
!W
Example 3: ANSYS finite element surface charges First, we prepare a model of a small box of dielectric material between two conductor plates at different voltages. A charge equivalent to 1234567 electrons is distributed over the 6 faces of the small box: !W
  FINISH  
  /CLEAR,START
  /PREP7  
  ! No polynomial elements
  /PMETH,OFF,1

  ! Set electric preferences
  KEYW,PR_ELMAG,1
  KEYW,MAGELC,1   

  ! Select element
  ET,1,SOLID123

  ! Material properties
  MP,PERX,1,1e10  ! Metal
  MP,RSVX,1,0.0   !
  MP,PERX,2,1.0   ! Gas
  MP,PERX,3,5.0   ! Permittivity of the box

  ! Parameters of the device
  unit = 1000              ! Units: 1000 for mm, 100 for cm, 1 for m
  r = 10                   ! Radius [mm]
  box = 50                 ! Surrounding box
  qe = 1.60217646e-19      ! Electron charge [C]
  charge = 1234567*unit*qe ! Total charge in the device

  ! Model a box in a block
  BLOCK, -box, box, -box, box, -box, box
  BLOCK, -r,   r,   -r,   r,   -r,   r

  ! Subtract the small box from the block
  VSBV,  1, 2, , , KEEP   ! 1 -> 3

  ! Glue everything together
  VGLUE, ALL

  ! Assign material attributes
  VSEL, S,,, 3
  VATT, 2
  VSEL, S,,, 2
  VATT, 3

  ! Voltage boundaries on the planes
  VSEL, ALL
  ASEL, S, LOC, Z, box
  DA, ALL, VOLT, 100
  ASEL, S, LOC, Z, -box
  DA, ALL, VOLT, 200

  ! Distribute charges over the surfaces of the small box
  VSEL, S,,,2
  ASLV, S
  SFA,ALL,,CHRGS,charge/(2*6*4*r*r)

  ! Meshing
  VSEL, S,,, 2, 3
  ASLV, S
  MSHKEY,0
  SMRT, 1
  VMESH, ALL

  ! Solve the field
  /SOLU
  SOLVE
  FINISH  

  ! Plot
  /POST1  
  /EFACET,1   
  PLNSOL, VOLT,, 0

  ! Write the solution to files
  /OUTPUT, PRNSOL, lis
  PRNSOL
  /OUTPUT

  /OUTPUT, NLIST, lis
  NLIST,,,,COORD
  /OUTPUT

  /OUTPUT, ELIST, lis
  ELIST
  /OUTPUT

  /OUTPUT, MPLIST, lis
  MPLIST
  /OUTPUT
!W
Next we read the field maps and integrate the charge around the small box. The model has been prepared in units of mm, as shown by the charge correction factor ("unit" in the above script). We need to inform Garfield about this choice when reading the field maps. !W
  "-> &CELL"
  "-> &CELL -> field-map" files "~/scratch0/PRNSOL.lis" ansys-solid-123 unit mm

  "-> &MAIN"
  "-> Global" r = 4               // sufficiently large to wrap around all charges
  "-> Global" eps0 = 8.854e-14    // C/(V.cm)
  "-> Global" qe = 1.60217646e-19 // C
  "-> Call" integrate_charge(0, 0, 0, r, qi)
  "-> Say" "Electron charges: {qi*4*pi*eps0/qe}"
!W
It is worth trying the above example for a smaller charge to observe that the field generated by a small charge is invisible in a finite element map. 2 INTEGRATE_FLUX Integrates the flux of the E field over a parallelogram. This procedure was written with classic (i.e. diffusion-free) estimates of the transparency of e.g. meshes in mind. More realistic estimates of such transparencies can be obtained with microscopic tracking techniques. Although this procedure can be used to determine the charge contained in a box, the "-> Call -> INTEGRATE_CHARGE" procedure is easier to use in case the integration can also be performed over a sphere. Note that there is a difference of 4\ \π between the normalisations of these two procedures (see Example 2). The parallelogram has (x0,y0,z0) as one of its corners while the two adjacent corners are (x0+dx1,y0+dy1,z1+dz1) and (x0+dx2,y0+dy2,z1+dz2). Integration is performed using 6-point Gaussian quadrature over (nu\ \×\ nv) equal intervals along the two sides of the rectangle. The arguments nu and nv are optional. They are by default set to 20. The flux is returned in Volt.cm. Format: !W
  CALL INTEGRATE_FLUX(x0,y0,z0, dx1,dy1,dz1, dx2,dy2,dz2, flux [, nu [, nv]])
!W
Example 1: Flux in a parallel plate device !W
  "-> &CELL"
  "-> &CELL -> plane" x=-1 v=-1000
  "-> &CELL -> plane" x=+1 v=+1000

  "-> &FIELD"
  Call flux(0,-1,-1, 0,2,0, 0,0,2, flux)
  "-> Say" "Flux={flux} [V.cm]"
!W
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\ \×\ 4\ cm\²\ =\ 4000\ V.cm Example 2: Relation with charge !W
  "-> &CELL"
  "-> &CELL -> field-map" files "~/scratch0/PRNSOL.lis" ansys-solid-123 unit mm

  "-> &MAIN"
  "-> Global" r = 4               // sufficiently large to wrap around all charges
  "-> Global" eps0 = 8.854e-14    // C/(V.cm)
  "-> Global" qe = 1.60217646e-19 // C
  "-> Call" "-> Call -> integrate_charge"(0, 0, 0, r, qi)
  "-> Say" "Electron charges: {qi*4*pi*eps0/qe}"

  "-> Global" r=4
  "-> Global" n=30
  "-> Call" integrate_flux(-r,-r,-r, 2*r,0,0, 0,2*r,0, f1, n, n)
  "-> Call" integrate_flux(-r,-r,-r, 0,2*r,0, 0,0,2*r, f2, n, n)
  "-> Call" integrate_flux(-r,-r,-r, 0,0,2*r, 2*r,0,0, f3, n, n)
  "-> Call" integrate_flux( r, r, r, 0,0,-2*r, 0,-2*r,0, f4, n, n)
  "-> Call" integrate_flux( r, r, r, 0,-2*r,0, -2*r,0,0, f5, n, n)
  "-> Call" integrate_flux( r, r, r, -2*r,0,0, 0,0,-2*r, f6, n, n)
  "-> Say" {f1,f2,f3,f4,f5,f6}
  "-> Global" qj = f1+f2+f3+f4+f5+f6
  "-> Say" "Electron charges: {-qj*eps0/qe}"
!W
This example computes the total charge for the field map used in Example 3 for "-> Call -> INTEGRATE_CHARGE" by summing the flux through the 6 faces of a box enclosing the charges. Note that INTEGRATE_FLUX, contrary to INTEGRATE_CHARGE does not divide the flux by a factor 4\ \π. The difference in sign is due to the orientation of the panels. 2 INTEGRATE_EXCITATIONS Integrates the excitation rates over the current drift path to obtain the total number of excited molecules along the path. The procedure returns a "-> algebra -> variables -> types -> Matrix" with separate counts for each of the excited states. An electron drift-line must be computed before the present procedure is called. Currently, only "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integrated electron drift-lines can be processed, pending validation of the integration method. Such drift-lines can be calculated using the "-> Call -> DRIFT_ELECTRON" and "-> Call -> DRIFT_ELECTRON_3" procedures. Excitation rates are computed by Magboltz as a side product of the calculation of the transport parameters. These rates can be visualised and printed using the "-> &GAS -> OPTIONS -> GAS-PLOT" and "-> &GAS -> OPTIONS -> GAS-PRINT" options of the gas section. The integration of these rates takes the underlying avalanche into account. Since both the excitation rates and the Townsend coefficients rise fast on approach of electrodes, the leading terms in the integrand are differences between terms of order exp(x\²) resp. exp(-x\²). To maintain precision, integration is split over 6 different regimes while the special functions that are used (the error function erf, the complement of error function erfc, the reduced complement of error function erfcr, the imaginary error function erfi and the reduced imaginary error function erfir) all have internally a set of approximations according to argument value. Although tested for a wide range of parameters, users are advised to carefully check the results that are obtained with this procedure. The accuracy of this procedure is controlled by the setting of the TOWNSEND-ACCURACY and TOWNSEND-STACK-DEPTH "-> &DRIFT -> INTEGRATION-PARAMETERS" Format: !W
  CALL INTEGRATE_EXCITATIONS(rates)
!W
Example: !W
  Call "-> Call -> drift_electron"(-0.3,0.2,status,time,diff,gain)
  Call "-> Call -> level_count"(nexc, nion)
  Call integrate_excitations(ex)
  For i From 1 To nexc Do
     Call "-> Call -> excitation_identifier"(i,name)
     Say "Level {i}: {"-> algebra -> functions -> number"(ex[i])} ({name})."
  Enddo
!W
This example calculates an electron drift-line from (-0.3,0.2) and lists the total number of excited molecules produced along the path. 2 INTEGRATE_IONISATIONS Integrates the ionisation rates over the current drift path to obtain the total number of ionised molecules along the path. The procedure returns a "-> algebra -> variables -> types -> Matrix" with separate counts for each of the ionised states. An electron drift-line must be computed before the present procedure is called. Currently, only "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" integrated electron drift-lines can be processed, pending validation of the integration method. Such drift-lines can be calculated using the "-> Call -> DRIFT_ELECTRON" and "-> Call -> DRIFT_ELECTRON_3" procedures. Ionisation rates are computed by Magboltz as a side product of the calculation of the transport parameters. These rates can be visualised and printed using the "-> &GAS -> OPTIONS -> GAS-PLOT" and "-> &GAS -> OPTIONS -> GAS-PRINT" options of the gas section. A priori, the number of ionised molecules should be the same as the number of avalanche electrons. As can easily be checked, this is not really the case. This is related to the way the velocity is computed when determining the Townsend coefficient. The integration of these rates takes the underlying avalanche into account. Since both the ionisation rates and the Townsend coefficients rise fast on approach of electrodes, the leading terms in the integrand are differences between terms of order exp(x\²) resp. exp(-x\²). To maintain precision, integration is split over 6 different regimes while the special functions that are used (the error function erf, the complement of error function erfc, the reduced complement of error function erfcr, the imaginary error function erfi and the reduced imaginary error function erfir) all have internally a set of approximations according to argument value. Although tested for a wide range of parameters, users are advised to carefully check the results that are obtained with this procedure. The accuracy of this procedure is controlled by the setting of the TOWNSEND-ACCURACY and TOWNSEND-STACK-DEPTH "-> &DRIFT -> INTEGRATION-PARAMETERS" Format: !W
  CALL INTEGRATE_IONISATIONS(rates)
!W
Example: !W
  Call "-> Call -> drift_electron"(-0.3,0.2,status,time,diff,gain)
  Call "-> Call -> level_count"(nexc, nion)
  Call integrate_ionisations(ion)
  For i From 1 To nion Do
     Call "-> Call -> ionisation_identifier"(i,name)
     Say "Level {i}: {"-> algebra -> functions -> number"(ion[i])} ({name})."
  Enddo
!W
2 INTERNAL_TO_CARTESIAN Applies the conformal mapping of internal (\ρ,\φ) coordinates to Cartesian (x,y) coordinates. The (\ρ,\φ) coordinates are used internally in the program when the cell is described in polar coordinates. Internal coordinates are related to Cartesian coordinates by: !W
  x = cos(\φ)*exp(\ρ)        [\φ in radian, x in cm]
  y = sin(\φ)*exp(\ρ)        [\φ in radian, y in cm]
!W
The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL INTERNAL_TO_CARTESIAN(\ρ,\φ,x,y)
!W
2 INTERNAL_TO_POLAR Converts internal (\ρ,\φ) coordinates to polar (r,\φ') coordinates. The (\ρ,\φ) coordinates are used internally in the program when the cell is described in polar coordinates. Internal coordinates are related to polar coordinates by: !W
  r  = exp(\ρ)      [dimensions not defined]
  \φ' = 180*\φ/\π     [\φ' in degrees]
!W
The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL INTERNAL_TO_CARTESIAN(\ρ,\φ,x,y)
!W
2 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 "-> Call -> INTERPOLATE_i" (i = 1, 2, 3 or 4) procedures which furthermore permit higher order polynomial interpolation. The procedure is based on the CERN library routine !D1 FINT. !WFINT and in addition verifies that the points at which interpolations are requested, are within the ranges of the ordinate vectors. If a point is located outside these ranges, then a value of 0 is returned, without warning message. Format: !W
  CALL INTERPOLATE("-> Call -> INTERPOLATE -> matrix", "-> Call -> INTERPOLATE -> ord"_1, ... ord_n, "-> Call -> INTERPOLATE -> points", "-> Call -> INTERPOLATE -> out")
!W
Example: !W
  Call "-> 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 "-> Call -> dimensions"(time,ndim_time,dim_time)
  Call "-> Call -> book_matrix"(point,2,dim_time[1])
  Call "-> Call -> delete_matrix"(dim_time)
  Global point[1;]=z_hit
  Global point[2;]=time

  Call interpolate(delta,z,time,point,trans)
  Call "-> Call -> delete_matrix"(point)
!W
The matrix delta contains the \δ-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 \δ-response for intermediate values of z by interpolation. 3 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. 3 ord Vectors of ordinates, one vector is required along each of the dimensions of the matrix. 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. 3 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. 2 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 "-> Call -> INTERPOLATE" procedure. Format: !W
  CALL INTERPOLATE_i(x_"-> Call -> INTERPOLATE_i -> vector", y_vector, "-> Call -> INTERPOLATE_i -> x", "-> Call -> INTERPOLATE_i -> y")
!W
Example: !W
  "-> &FIELD"
  "-> &FIELD -> select" 1
  "-> &FIELD -> 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}."
!W
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\° are not present in these vectors, one uses one of the INTERPOLATE_i procedures to interpolate for these angles. 3 method This procedure uses, depending on the compilation, either the ESSL routine STPINT or the CERNLIB procedure !D1 DIVDIF. !WDIVDIF. 3 vector Both x_vector and y_vector should be a 1-dimensional "-> algebra -> variables -> types -> 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 or in strictly decreasing order, i.e. an element may not be equal to the element preceding or following it. [These are mandatory arguments, no defaults are supplied.] 3 x The coordinate at which interpolation is to be performed should either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix" of any shape. In either case, all values should be in the range spanned by the x_"-> Call -> INTERPOLATE_i -> vector". If a 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.] 3 y Contains, on successful completion, the result of the interpolation in the form of a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Number" with a shape identical that the shape of "-> Call -> INTERPOLATE_i -> x". Any value associated with this argument at the time the procedure is called, is lost after execution of the procedure. [This is a mandatory argument.] 2 INTERPOLATE_TRACK Performs an interpolation, at a given location, of a track that has been prepared with "-> &DRIFT -> 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: !W
  CALL INTERPOLATE_TRACK(x, y, z, "-> Call -> INTERPOLATE_TRACK -> status" [, "-> Call -> INTERPOLATE_TRACK -> time" [, ...
     "-> Call -> INTERPOLATE_TRACK -> diffusion" [, "-> Call -> INTERPOLATE_TRACK -> multiplication" [, "-> Call -> INTERPOLATE_TRACK -> attachment" [, "-> Call -> INTERPOLATE_TRACK -> angle"]]]]])
!W
Example: !W
  Global n 20
  track 0.5 -0.9 0.5 0.9 lines {n}
  prepare-track
  Call "-> Call -> book_matrix"(yvec,n)
  Call "-> Call -> book_matrix"(tvec,n)
  Call "-> Call -> book_matrix"(dvec,n)
  Call "-> Call -> book_matrix"(avec,n)
  Call "-> Call -> book_matrix"(bvec,n)
  Call "-> Call -> new_track"
  For i From 1 To n Do
     Call "-> 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 "-> Call -> plot_graph"(yvec,tvec,`y [cm]`,`Time [microsec]`, ...
     `Drift time`)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_graph"(yvec,dvec,`y [cm]`,`Diffusion [microsec]`, ...
     `Diffusion`)
  Call "-> Call -> plot_end"
  Call "-> Call -> plot_graph"(yvec,avec*bvec,`y [cm]`,`Electron`, ...
     `Multiplication and loss`)
  Call "-> Call -> plot_end"
!W
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. 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 3 diffusion See "-> Call -> DRIFT_ELECTRON -> diffusion". 3 multiplication See "-> Call -> DRIFT_ELECTRON -> multiplication". 3 attachment See "-> Call -> DRIFT_ELECTRON -> attachment". 3 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.] 2 IONISATION_IDENTIFIER Returns the identifier of an ionisation level. This procedure is used to identify the rates that are returned by "-> Call -> INTEGRATE_IONISATIONS". The first argument is the level number, the index of the vector given by INTEGRATE_IONISATIONS. The second argument contains on return a string with the level identifier, which is described in somewhat more detail in the gas "-> &GAS -> MAGBOLTZ -> ingredient"s. The optional third argument contains on return the threshold energy of the level (in eV). The number of levels can be obtained with "-> CALL -> LEVEL_COUNT". Format: !W
  CALL IONISATION_IDENTIFIER(level_number, level_identifier [, level_energy])
!W
For examples, see "-> Call -> INTEGRATE_IONISATIONS" and "-> Call -> LEVEL_COUNT". 2 IONISATION_RATE Returns the rate at which an ionised state is formed, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the rates (at least in principle) depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The first argument is a "-> algebra -> variables -> types -> Number" which identifies the level. The number of available levels can be found with the "-> Call -> LEVEL_COUNT" procedure and further information can be obtained with "-> Call -> IONISATION_IDENTIFIER". The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the rate is returned in THz. Formats: !W
  CALL IONISATION_RATE(level, e, rate)
  CALL IONISATION_RATE(level, ex, ey, ez, rate)
  CALL IONISATION_RATE(level, ex, ey, ez, bx, by, bz, rate)
!W
Example: !W
  "-> Global" emin=5000
  "-> Global" emax=25000
  "-> Global" e=emin*(emax/emin)^(("-> algebra -> functions -> row"(200)-1)/199)
  Call "-> Call -> plot_frame"(emin/1000, 0, emax/1000, 100, `E [kV/cm]`, ...
     `Ionisation rate [MHz]`, `Ionisations`)
  Call "-> Call -> level_count"(nexc, nion)
  For id From 1 To nion Do
     Call ionisation_rate(id,e,ion)
     Call "-> Call -> plot_line"(e/1000,ion*1e6, `"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Enddo
  Enddo
  Call "-> Call -> plot_end"
!W
This examples makes a simple plot of all ionisation rates, similar to the one obtained when using the "-> &GAS -> OPTIONS -> GAS-PLOT" option, but with a customised range. 2 ION_DISSOCIATION Returns the ion dissociation coefficients, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The dissociation coefficient is returned in 1/cm. Formats: !W
  CALL ION_DISSOCIATION(e, dissociation)
  CALL ION_DISSOCIATION(ex, ey, ez, dissociation)
  CALL ION_DISSOCIATION(ex, ey, ez, bx, by, bz, dissociation)
!W
2 ION_MOBILITY Returns the ion mobility, if available, for a given value electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. Although to my knowledge not yet measured, the ion mobility may depend on the magnetic field as well as on the angle between the electric and magnetic field. If such dependence has been entered in the gas tables, then it can be retrieved with this procedure. Both fields then have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm, the magnetic field, if present, in native units of 0.01\ T or 100\ G. The ion mobility is returned in cm\²/V.\μsec. Formats: !W
  CALL ION_MOBILITY(e, mobility)
  CALL ION_MOBILITY(ex, ey, ez, mobility)
  CALL ION_MOBILITY(ex, ey, ez, bx, by, bz, mobility)
!W
2 ION_VELOCITY Returns the ion drift "-> &DRIFT -> methods -> velocity" vector at a point. This procedure needs ion mobility data, which can for instance be entered with the "-> &GAS -> TABLE" and "-> &GAS -> 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 "-> &DRIFT -> SPEED" command. Format: !W
  CALL ION_VELOCITY(x, y, z, vx, vy, vz [, status])
!W
Example: !W
  Call ion_velocity(2,3,0,vx,vy,vz,status)
  Say "Velocity: ({vx,vy,vz}), Status: {status}"
!W
3 coordinates This procedure accepts coordinates of type "-> algebra -> variables -> types -> 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: z
!W
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 "-> Call -> POLAR_TO_INTERNAL" procedure. 3 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: !W
  vr = vx/r
  vphi = vy/r
  vz is invariant
!W
3 status See "-> Call -> ELECTRIC_FIELD -> status". 2 LEVEL_COUNT Returns the number of excitation and ionisation levels in the gas data. These counts are used to loop over the states as shown in the example. Excitation and ionisation rates are computed by Magboltz as a side product when generating transport tables. Magboltz distinguishes a large number of individual levels. The list of gas mixture "-> &GAS -> MAGBOLTZ -> ingredient"s contains a brief descriptions of these levels. The "-> Call -> INTEGRATE_EXCITATIONS" and "-> Call -> INTEGRATE_IONISATIONS" procedures integrate the rates, returning vectors of integrated rates. The correspondence between the indices of these vectors and the level identifiers is established by the "-> Call -> EXCITATION_IDENTIFIER" and "-> Call -> IONISATION_IDENTIFIER" procedures. Format: !W
  CALL LEVEL_COUNT(n_excitations, n_ionisations)
!W
Example: !W
  Call level_count(nexc, nion)
  For i From 1 To nexc Do
     Call "-> Call -> excitation_identifier"(i,name, e)
     Say "Excitation {i}: {name}, threshold energy = {e} eV"
  Enddo
  For i From 1 To nion Do
     Call "-> Call -> ionisation_identifier"(i,name, e)
     Say "Ionisation {i}: {name}, threshold energy = {e} eV"
  Enddo
!W
2 LIST_HISTOGRAMS Prints a summary of all histograms currently in storage, showing the current average, RMS and number of entries as well as the range if set. Also shown are the names of the "-> Global" variables associated with each histogram. Histograms should in principle always be associated with a global variable. Memory leaks can occur however because of incomplete garbage collects. If all available memory is occupied by orphan histograms, then memory can be freed with the "-> Call -> DELETE_HISTOGRAM" procedure. Format: !W
  CALL LIST_HISTOGRAMS
!W
Example: !W
  Call "-> Call -> book_histogram"(hist,50,`integer`)
  Call list_histograms
  For i From 1 To 10000 Do
     Call "-> Call -> fill_histogram"(hist,rnd_poisson(10))
  Enddo
  Call list_histograms
!W
An histogram is booked in autorange mode with integer bins. The listing will indicate this, adding that there are no entries yet. During filling, the range of the histogram is set, as is revealed in the second listing. 2 LIST_MATRICES LIST_MATRICES prints an overview of matrices currently in memory and of the "-> Global" variables associated with them. Matrices should in principle always be associated with a global variable. Memory leaks can occur however because of incomplete garbage collects. If all available memory is occupied by orphan matrices, then memory can be freed with the "-> Call -> DELETE_MATRIX" procedure. Format: !W
  CALL LIST_MATRICES
!W
Example: !W
  Call "-> Call -> book_matrix"(a,2,3,4,5)
  Call "-> Call -> list_matrices"
  Call "-> Call -> delete_matrix"(a)
  Call list_matrices
!W
2 LIST_OBJECTS Lists the current booking state of all known objects. Objects are e.g. memory areas which can be shared by various calculations. Some procedures can proceed faster if some area of memory contains data of a certain kind, and they test this by looking into the object booking list. Usually, you do not need to worry about this. !W
  CALL LIST_OBJECTS
!W
Example: !W
  &CELL
  rows
  s 5 * i i 1000*i

  &FIELD
  Call list_objects
  plot surf v
  Call list_objects
!W
Will show that the area called MATRIX is first used for the capacitance matrix. Once the charges have been computed, the area is released. It is claimed again for making the surface plot, and released once this plot has been made. The capacitance matrix is lost at this point, and e.g. "-> &OPTIMISE -> CHANGE-VOLTAGES" would now recompute the capacitance matrix. 2 LIST_RAW_SIGNALS Lists the raw signals that are currently in store. Raw signals can be retrieved using the "-> Call -> GET_RAW_SIGNAL" procedure. Format: !W
  CALL LIST_RAW_SIGNALS
!W
Example: !W
  &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 -> signal"
  Call list_raw_signals
  Call get_raw_signal(`ion`,1,1,0,time,sig)
  Call "-> Call -> plot_frame"(0,0,4,10,` `,` `,` `)
  Call "-> Call -> plot_line"(time,sig)
  Call "-> Call -> plot_end"
!W
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. 2 LIST_STRINGS Lists all currently known strings, their length, current value and association with "-> Global" variables. Unlike histograms and matrices, not all strings are associated with a global. For instance, names of metafiles are kept in the string buffer. Format: !W
  CALL LIST_STRINGS
!W
Example: !W
  Global a=`This is a string`
  Call string_listing
!W
2 LOCATE_MAXIMUM Returns the indices of the maximum of a matrix. Use the "-> algebra -> functions -> MAXIMUM" function instead if you only need to know the value, and not the location, of the maximum. Format: !W
  CALL LOCATE_MAXIMUM("-> Call -> LOCATE_MAXIMUM -> matrix", "-> Call -> LOCATE_MAXIMUM -> index"_1,index_2, ... , index_n)
!W
Example: !W
  Call "-> Call -> book_matrix"(a,3,3,3)
  For i From 1 To 3 Do
     For j From 1 To 3 Do
        For k From 1 To 3 Do
           Global a[i;j;k]=(i-1)*(j-2)*(k-3)
        Enddo
     Enddo
  Enddo
  Call locate_maximum(a,imax,jmax,kmax)
  Say "Maximum is at A[{imax};{jmax};{kmax}] = {a[imax;jmax;kmax]},"
  Say "which should be equal to {maximum(a)}."
!W
3 matrix Should, when the procedure is called, contain the "-> algebra -> variables -> types -> Matrix" which is to be searched for a maximum. The matrix is allowed to have arbitrary dimensions. This argument is mandatory and is not modified by the procedure. 3 index Each of these arguments contains on successful completion a "-> algebra -> variables -> types -> Number" which together can be used to address the maximum. There should be as many arguments of this type as the matrix has dimensions. The value of this argument on input is not used and is lost after the procedure call. 2 LOCATE_MINIMUM Returns the indices of the minimum of a matrix. Use the "-> algebra -> functions -> MINIMUM" function instead if you only need to know the value, and not the location, of the minimum. Format: !W
  CALL LOCATE_MINIMUM("-> Call -> LOCATE_MINIMUM -> matrix", "-> Call -> LOCATE_MINIMUM -> index"_1,index_2, ... , index_n)
!W
Example: !W
  Call "-> Call -> book_matrix"(a,3,3,3)
  For i From 1 To 3 Do
     For j From 1 To 3 Do
        For k From 1 To 3 Do
           Global a[i;j;k]=(i-1)*(j-2)*(k-3)
        Enddo
     Enddo
  Enddo
  Call locate_minimum(a,imin,jmin,kmin)
  Say "Minimum is at A[{imin};{jmin};{kmin}] = {a[imin;jmin;kmin]},"
  Say "which should be equal to {minimum(a)}."
!W
3 matrix Should, when the procedure is called, contain the "-> algebra -> variables -> types -> Matrix" which is to be searched for a minimum. The matrix is allowed to have arbitrary dimensions. This argument is mandatory and is not modified by the procedure. 3 index Each of these arguments contains on successful completion a "-> algebra -> variables -> types -> Number" which together can be used to address the minimum. There should be as many arguments of this type as the matrix has dimensions. The value of this argument on input is not used and is lost after the procedure call. 2 LONGITUDINAL_DIFFUSION Returns the longitudinal diffusion, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The diffusion is returned in \√cm. The "-> &GAS -> methods -> coordinate_system" aligns the longitudinal diffusion with the electric field, not necessarily with the drift velocity vector. The transverse diffusion is the average of the diffusion perpendicular to E. SIGMA_L can be typed as a synonym to LONGITUDINAL_DIFFUSION. Formats: !W
  CALL LONGITUDINAL_DIFFUSION(e, sigma_l)
  CALL LONGITUDINAL_DIFFUSION(ex, ey, ez, sigma_l)
  CALL LONGITUDINAL_DIFFUSION(ex, ey, ez, bx, by, bz, sigma_l)
!W
2 LORENTZ_ANGLE Returns the Lorentz angles, if available, for a given value of (Ex, Ey, Ez) and (Bx, By, Bz) or a given set of values of (Ex, Ey, Ez) and (Bx, By, Bz). If the fields are 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 fields 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 magnetic field in native units of 0.01\ T or 100\ G. The Lorentz angles are returned in radians. Format: !W
  CALL LORENTZ_ANGLE(ex, ey, ez, bx, by, bz, angle)
!W
2 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. The arguments bx, by, bz, and b are optional. Format: !W
  CALL MAGNETIC_FIELD(x, y, bx, by, bz [, b])
!W
3 coordinates This procedure accepts input arguments of types "-> algebra -> variables -> types -> Number" and "-> algebra -> variables -> types -> 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 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: !W
  for x: log(r)
  for y: \φ, in radians
!W
These mappings can be performed with the "-> Call -> POLAR_TO_INTERNAL" procedure. 3 field The field is returned in internal coordinates and internal units. 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: !W
  Br = Bx/r
  Bphi = By/r
  Bz = Bz
!W
The internal units for the magnetic field are 100\ G or 0.01\ T. 2 MAGNETIC_FIELD_3 Returns the magnetic field vector at a given point. The arguments bx, by, bz and b are optional. Format: !W
  CALL MAGNETIC_FIELD_3(x, y, z, bx, by, bz [, b])
!W
3 coordinates This procedure accepts input arguments of types "-> algebra -> variables -> types -> Number" and "-> algebra -> variables -> types -> Matrix". If at least one of the input arguments x, y, z is of type "-> algebra -> variables -> types -> 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 "-> algebra -> variables -> types -> 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 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: z
!W
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 "-> Call -> POLAR_TO_INTERNAL" procedure. 3 field The field is returned in internal coordinates and internal units. 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: !W
  Br = Bx/r
  Bphi = By/r
  Bz = Bz
!W
The internal units for the magnetic field are 100\ G or 0.01\ T. 2 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 "-> Call -> MAP_INDEX" procedure. The dielectric constant of the element can be found with "-> Call -> MAP_MATERIAL". The output arguments depend on the elements used in the field map: !Wul_start - triangles: 3\ pairs of (x,y) coordinates which correspond with the 3\ corners of the element; - quadrilaterals: 4\ pairs of (x,y) coordinates which correspond with the 4\ corners of the element; - tetrahedrons: 4\ sets of (x,y,z) coordinates which correspond to the 4\ vertices; - hexahedra: 8\ sets of (x,y,z) coordinates which correspond to corners, in case the hexehedron is degenerate, points 4 and 1, resp. 8 and 5 will be identical !Wul_end If the element does not exist, then a warning is printed, the global variable "-> algebra -> variables -> predefined -> OK" is set to False and the return arguments are not touched. This procedure is meaningful only when the field is generated by a field map. This procedure is used for debugging such maps. Formats: !W
  CALL MAP_ELEMENT(element, x1, y1, x2, y2, x3, y3)
  CALL MAP_ELEMENT(element, x1, y1, x2, y2, x3, y3, x4, y4)
  CALL MAP_ELEMENT(element, x1, y1, z1, x2, y2, z1, x3, y3, z3, ...
     x4, y4, z4)
  CALL MAP_ELEMENT(element, x1, y1, z1, x2, y2, z1, x3, y3, z3, ...
     x4, y4, z4, x5, y5, z5, x6, y6, z6, x7, y7, z7, x8, y8, z8)
!W
Example: !W
  Call "-> Call -> plot_frame"(-1.6,-1.6,1.6,1.6,`x [cm]`,`y [cm]`,`Mesh structure`)
  For i From 1 Step 1 "-> Do -> Until" ^"-> algebra -> variables -> predefined -> OK" To 10000 "-> Do"
     Call map_element(i,x1,y1,x2,y2,x3,y3)
     If ^OK Then "-> Do -> Leave"
     Call plot_area(x1,y1,x2,y2,x3,y3,`material-2`)
  Enddo
  Call "-> Call -> plot_end"
!W
This example assumes a triangular map of less than 10000 elements. It fetches one element at the time, then plots it. 2 MAP_INDEX Returns the index of the field map element in which a point is located, and optionally also the local triangular, quadrilateral, tetrahedron or hexahedral or, for degenerate hexahedra, mixed triangular/hexahedral coordinates of the point. Currently, all coordinate systems are isoparametric. The arguments to be provided depend on the elements used in the field map: !Wul_start - triangles: (x,y) should be specified and (t1,t2,t3) will be returned; - quadrilaterals: (x,y) should be specified and (t1,t2) will be returned; - tetrahedrons: (x,y,z) should be specified and (t1,t2,t3,t4) will be returned; - hexahedra: (x,y,z) should be specified and (t1,t2,t3) will be returned. !Wul_end Use the "-> Call -> MAP_ELEMENT" procedure to obtain geometric information about the field map element. The "-> Call -> MAP_MATERIAL" procedure supplies information on the material with which the element is filled. This procedure does not reduce the input coordinates to the elementary cell, even if the cell has been declared to have symmetries. If the point is not located in any element, then a warning is printed, the global variable "-> algebra -> variables -> predefined -> OK" is set to False and the return arguments of the procedure are not touched. Due to numerical rounding errors, points which are located in the immediate vicinity of the boundaries of the field map, are sometimes mistakenly declared to be outside the map. One should therefore test on OK. This procedure is meaningful only when the field is generated by a field map. This procedure is used for debugging such maps. Format: !W
  CALL MAP_INDEX(x, y [, z], element, [t1, t2, t3 [,t4]])
!W
2 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 "-> Call -> MAP_INDEX" procedure. The geometric aspects of the element can be found with "-> Call -> MAP_ELEMENT". If the element does not exist, then a warning is printed, the global variable "-> algebra -> variables -> predefined -> OK" is set to False and the return arguments of the procedure are not touched. Format: !W
  CALL MAP_MATERIAL(element, material, \ε)
!W
Example: !W
  "-> Global" xmin=-0.0100
  Global xmax=+0.0100
  Global ymin=-0.0180
  Global ymax=+0.01800
  Global z=0.0032
  Global n=50
  !rep "-> graphics -> REPRESENTATION -> item -> function-1" polymarker-colour green marker-type circle marker-size 0.2
  !rep "-> graphics -> REPRESENTATION -> item -> function-2" polymarker-colour blue  marker-type circle marker-size 0.2
  !rep "-> graphics -> REPRESENTATION -> item -> function-3" polymarker-colour red   marker-type circle marker-size 0.2
  Call "-> 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 "-> Call -> map_index"(x,y,0,index)
        Call map_material(index,ieps,eps)
        If eps<4 Then Iterate
        Call "-> Call -> electric_field_3"(x,y,z,ex,ey,ez,e)
        If ez<0 Then
           Call "-> Call -> plot_markers"(x,y,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
        Elseif ez>5000 Then
           Call "-> Call -> plot_markers"(x,y,`"-> graphics -> REPRESENTATION -> item -> function-3"`)
        Else
           Call "-> Call -> plot_markers"(x,y,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
        Endif
     Enddo
  Enddo
  Call "-> Call -> plot_end"
!W
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\ \μm) over a grid of n\ \×\ 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. 2 MATRIX_TO_HISTOGRAM Creates an "-> algebra -> variables -> types -> Histogram" with a number of channels equal to the number of elements of the "-> algebra -> variables -> types -> Matrix", and then interprets the elements of the matrix as number of entries in the bins of the histogram. You must specify the range, which is a set of two "-> algebra -> variables -> types -> Number"s. 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. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the conversion has been performed and to False if it hasn't. Format: !W
  CALL MATRIX_TO_HISTOGRAM(matrix, min, max, hist)
!W
Example: !W
  Call histogram_to_matrix(heheed,mat,x0,x1)
  Call matrix_to_histogram(mat,1e6*x0,1e6*x1,heheed)
!W
This example illustrates how one can change the horizontal scale of a matrix. With the help of a call to "-> CALL -> HISTOGRAM_TO_MATRIX", the range of the histogram HEHEED is obtained and stored in the variables X0 and X1. The contents is stored in the vector MAT. The subsequent call to MATRIX_TO_HISTOGRAM overwrites the original histogram by one that has the same bin contents, but an horizontal scale increased by a factor 1e6. 2 MICROSCOPIC_AVALANCHE Performs microscopic tracking of an electron and its secondaries. This procedure will optionally also compute signals. Refer to "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" for a description of the techniques used and the precautions to be taken. After a call to this procedure, one can obtain the start and end location of all electrons in the avalanche with the "-> Call -> AVALANCHE_INFORMATION" procedure. This feature can e.g. be used to compute the ion trajectories. Format: !W
  CALL MICROSCOPIC_AVALANCHE("-> Call -> MICROSCOPIC_AVALANCHE -> x", "-> Call -> MICROSCOPIC_AVALANCHE -> y", "-> Call -> MICROSCOPIC_AVALANCHE -> z", "-> Call -> MICROSCOPIC_AVALANCHE -> options", "-> Call -> MICROSCOPIC_AVALANCHE -> e_maximum", "-> Call -> MICROSCOPIC_AVALANCHE -> e_start", ...
       "-> Call -> MICROSCOPIC_AVALANCHE -> dir"_x, "-> Call -> MICROSCOPIC_AVALANCHE -> dir"_y, "-> Call -> MICROSCOPIC_AVALANCHE -> dir"_z, "-> Call -> MICROSCOPIC_AVALANCHE -> distribution", "-> Call -> MICROSCOPIC_AVALANCHE -> rates", "-> Call -> MICROSCOPIC_AVALANCHE -> n_electron", "-> Call -> MICROSCOPIC_AVALANCHE -> n_ion", "-> Call -> MICROSCOPIC_AVALANCHE -> delay")
!W
Example: !W
  Call "-> Call -> plot_drift_area"
  Call "-> Call -> new_track"
  Do
     Call "-> Call -> get_cluster"(x,y,z,n,e,done)
     If done Then "-> Do -> Leave"
     Call microscopic_avalanche(x, y, z, ...
        `mark-ion nomark-super mark-att print plot-electron abort-10000`, ...
        200.0, 1.0, 0,0,0, histe, rates, ne, ni)
     "-> Say" "Electrons: {ne}, Ions: {ni}"
  Enddo
  Call "-> Call -> plot_track"
  Call "-> Call -> plot_end"
!W
In this example, all electrons generated along a track, as well as the avalanches they generate are traced up to a size of 10000. The electron trajectories are plotted and locations where ionisation and attachment occurs are marked. 3 x x-Coordinate of the primary electron. See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 y y-Coordinate of the primary electron. See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 z z-Coordinate of the primary electron. See "-> Call -> DRIFT_ELECTRON -> coordinates". 3 status See "-> Call -> DRIFT_ELECTRON -> status". 3 time See "-> Call -> DRIFT_ELECTRON -> time". 3 options A "-> algebra -> variables -> types -> String" which may contain one or more of the following options and their negated versions (prefixed with NO): !Wdl_start !T+ + ----------------------------------------------------------------------------------- Option Description ----------------------------------------------------------------------------------- ABORT-100 Kills avalanche tracing when it reaches a size of 100. By default, an avalanche is allowed to grow until it exhausts the memory allocated for it. ABORT-1000 Kills avalanche tracing when it reaches a size of 1000. By default, an avalanche is allowed to grow until it exhausts the memory allocated for it. ABORT-10000 Kills avalanche tracing when it reaches a size of 10000. By default, an avalanche is allowed to grow until it exhausts the memory allocated for it. ABORT-100000 Kills avalanche tracing when it reaches a size of 100000. By default, an avalanche is allowed to grow until it exhausts the memory allocated for it. MARK-ATTACHMENT Marks the location where attachment occurs with representation "-> graphics -> REPRESENTATION -> item -> ATTACHMENT". The electron will as a rule stop at these locations. This option is not active by default. MARK-ELASTIC Marks the locations of elastic interactions, using "-> graphics -> REPRESENTATION -> item -> ELASTIC". This is nearly always the most common type of collision. This option is not active by default. MARK-EXCITATION Marks the locations of inelastic collisions where an excited state is produced. The point will be drawn using "-> graphics -> REPRESENTATION -> item -> EXCITATION". This option is not active by default. MARK-INELASTIC Marks the locations of inelastic but non-exciting interactions. The position will be marked using "-> graphics -> REPRESENTATION -> item -> INELASTIC". This option is not active by default. MARK-IONISATION Marks the locations where ionisations occur using "-> graphics -> REPRESENTATION -> item -> IONISATION". This option is not active by default. MARK-SUPER-ELASTIC Marks the locations of super-elastic interactions using "-> graphics -> REPRESENTATION -> item -> SUPER-ELASTIC". This option is not active by default. PLOT-ELECTRON Plots all electron trajectories. "-> Call -> PLOT_DRIFT_LINE" would only show the last electron trajectory calculated, not the entire avalanche. PRINT Switches on Magboltz printing. Use the "-> OPTIONS -> DEBUG" option to obtain details for each step. SIGNAL Requests calculation of the signals for the electrons in the avalanche. Please note that ion signals need to be added separately, as illustrated in the example below. ----------------------------------------------------------------------------------- !Wdl_end Note: switching on any of the MARK and PLOT options presumes that you have already opened a graphics window suitable for plotting the drift-line. Example: !W
  // Options and arguments
  "-> Global" options = `plot-electron, abort-100`
  "-> Global" emax = 200
  "-> Global" estart = 0.1
  "-> Global" xstart = -0.2+0.4*"-> algebra -> functions -> rnd_uniform"
  "-> Global" ystart = 0.8

  // Open a plot frame
  Call "-> Call -> plot_drift_area"
  // Microscopic avalanche
  Call microscopic_avalanche(xstart, ystart, 0, options, emax, estart, ...
     0, 0, 0, edist, rates, n_electron, n_ion)
  Say "Electrons: {n_electron}, ions: {n_ion}"

  // Retrieve the ion production point
  Call "-> Call -> avalanche_information"(`electrons`, ne)
  For ie From 2 To ne Do // No ion from the drift line starting point
     Call "-> Call -> avalanche_information"( ...
        `x-start`, ie, xion, `y-start`, ie, yion, `z-start`, ie, zion, ...
        `t-start`, ie, tion)
     Call "-> Call -> drift_ion_3"(xion, yion, zion)
     Call "-> Call -> plot_drift_line"
     Call "-> Call -> add_signals"(tion) // Offset with production time
  Enddo

  // Close  the plot
  Call "-> Call -> plot_end"
!W
The locations where ions are produced are retrieved using "-> Call -> AVALANCHE_INFORMATION" and the ions are drifted with "-> Call -> DRIFT_ION_3". The ion-induced signals are computed and added with "-> Call -> ADD_SIGNALS". 3 e_maximum Maximum kinetic energy in eV any electron in the avalanche is expected to reach. The calculation of the avalanche as a whole is aborted when at any point an electron energy exceeds this value. The global variable "-> algebra -> variables -> predefined -> OK" will be set to False should this occur. The trajectory will be inaccurate if the maximum energy is chosen too large. A simple way to find suitable values for this parameter is running "-> &GAS -> MAGBOLTZ" with the "-> &GAS -> MAGBOLTZ -> PLOT-DISTRIBUTION-FUNCTIONS" option switched on. Beware that e_maximum must be suitable over the entire drift path of the electron, including the avalanche region. [Default: 200 eV] 3 e_start Kinetic energy in eV of the primary electron at the start of the avalanche. The energy of secondary electrons is randomised according to a splitting function. This energy must be strictly positive (non-zero) and less than "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum". [Default: 2\ % of "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum".] 3 dir Direction vector of the initial velocity of the primary electron. The initial direction has, in most gaseous detectors, little impact. The direction of secondary electrons is assumed to be isotropic. The norm of the initial velocity is taken from "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_start", not from the direction vector. The normalisation is arbitrary. All three components must be specified. If all 3\ components of the direction vector are zero, then an isotropic random vector will be generated. [A random direction is assumed if no direction is specified.] 3 distribution On return an "-> algebra -> variables -> types -> Histogram" which contains the electron energy distribution sampled just prior to every interaction with the gas molecules. If this argument is on entry an existing histogram, then new entries will be added to it. This can be used to force a scale and also to accumulate statistics across multiple calls. If this argument is of another type on entry, then the current value will be deleted and a new histogram will be booked with 100\ bins and ranging from 0 to "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum". 3 rates This procedure returns the detailed counts of the interactions in the form of a 1-dimensional "-> algebra -> variables -> types -> Matrix". The cross sections present in the vector vary with "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> e_maximum" since Magboltz eliminates, for reasons of efficiency, negligibly small cross section terms. The various terms can be identified with the help of the "-> Call -> CROSS_SECTION_IDENTIFIER" procedure: See the "-> Call -> DRIFT_MICROSCOPIC_ELECTRON -> rates" argument of the "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure for an example. 3 n_electron Contains on return the "-> algebra -> variables -> types -> Number" of electrons produced in the avalanche minus the number of electrons lost via attachment. This is an optional output parameter. If present, it must be modifiable. The value assigned to this parameter on entry is not used and will be lost after the call. 3 n_ion Contains on return the "-> algebra -> variables -> types -> Number" of ions produced in the avalanche. This is an optional output parameter. If present, it must be modifiable. The value assigned to this parameter on entry is not used and will be lost after the call. 3 delay Starting time of the avalanche, in microsec. This option is used in conjuction with signal calculation, to offset the signals in time. [Default: 0 microsec.] 2 MULTIPLY_MATRICES (Not yet available) 2 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 "-> &DRIFT -> TRACK" command. Once NEW_TRACK has been called, cluster positions and cluster sizes can be obtained from "-> Call -> GET_CLUSTER". Format: !W
  CALL NEW_TRACK
!W
Example: See "-> Call -> GET_CLUSTER". 2 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 "-> Call -> PLOT_FRAME". Two formats are accepted: one takes a series of (x,y) coordinates, the other takes a pair of vectors as arguments. Formats: !W
  CALL PLOT_AREA("-> Call -> PLOT_AREA -> x"1, "-> Call -> PLOT_AREA -> y"1, x2, y2, ..., x_n, y_n [, "-> Call -> PLOT_AREA -> representation"])
  CALL PLOT_AREA("-> Call -> PLOT_AREA -> x_vector", "-> Call -> PLOT_AREA -> y_vector" [, representation])
!W
Example: !W
  !rep "-> graphics -> REPRESENTATION -> item -> times-roman" character-height 0.075 ch-exp {1.2/8.5}
  !rep "-> graphics -> REPRESENTATION -> item -> box-tickmarks" polyline-col background
  !rep "-> graphics -> REPRESENTATION -> item -> grid" polyline-col background
  !rep "-> graphics -> REPRESENTATION -> item -> numbers" text-col background
  Call "-> 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
           !"-> graphics -> colour" a red {i} green {j} blue {k}
           !rep "-> graphics -> REPRESENTATION -> item -> 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 "-> Call -> plot_text"(j+0.1,7*i+k+0.1, ...
                `R=`/"-> algebra -> functions -> string"(i)/`, B=`/string(k)/`, G=`/string(j), ...
                `TIMES-ROMAN`,`CENTRE-HALF`)
        Enddo
     Enddo
  Enddo
  Call "-> Call -> plot_end"
!W
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. 3 x One of the 2 formats of the PLOT_AREA procedure call, takes a series of (x,y) coordinates as argument to describe the line which is to be drawn. Each of the x and y coordinates should be of the type "-> algebra -> variables -> types -> Number". There should be at least 3 pairs of (x,y) coordinates if you use this format. The vector and scalar formats can not be mixed. [These are mandatory arguments, no default is supplied.] 3 y See "-> Call -> PLOT_AREA -> x". 3 x_vector One of the 2 formats of the PLOT_AREA procedure call, takes a pair of (x,y) coordinate vectors as argument. These vectors should both be a 1-dimensional "-> algebra -> variables -> types -> Matrix". The vectors must have an equal length of at least 3. The vector and scalar formats can not be mixed. [These are mandatory arguments, no default is supplied.] 3 y_vector See "-> Call -> PLOT_AREA -> x_vector". 3 representation The fill area representation that should be used, see "-> graphics -> REPRESENTATION" for further information. 2 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 "-> graphics -> ARROW-TIP-ANGLE" and "-> graphics -> ARROW-TIP-LENGTH". The start and end point of the arrow are interpreted in the user coordinate system even if a call to "-> Call -> GKS_SELECT_NT" has been issued prior to the PLOT_ARROW call. Format: !W
  CALL PLOT_ARROW("-> Call -> PLOT_ARROW -> x0", "-> Call -> PLOT_ARROW -> y0", "-> Call -> PLOT_ARROW -> x1", "-> Call -> PLOT_ARROW -> y1" [, "-> Call -> PLOT_ARROW -> representation"])
!W
Example: !W
  Call plot_arrow(0,0,1,1,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
!W
3 x0 x-Coordinate of the start of the arrow. This argument is not modified by the call and should be of type "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument.] 3 y0 y-Coordinate of the start of the arrow. This argument is not modified by the call and should be of type "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument.] 3 x1 x-Coordinate of the tip of the arrow. This argument is not modified by the call and should be of type "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument.] 3 y1 y-Coordinate of the tip of the arrow. This argument is not modified by the call and should be of type "-> algebra -> variables -> types -> Number". [No default, this is a mandatory argument.] 3 representation A polyline representation with which the arrow is to be drawn. This argument is not modified by the call and should be of type "-> algebra -> variables -> types -> String". [By default, the currently active polyline representation.] 2 PLOT_BARCHART Plots a bar chart with the specified labels along the x-axis and y-axis and with the given title. This procedure, by default, plots the bar chart in a frame with dimensions adjusted to the range of the points. If you wish to control the axes yourself, then use the "-> Call -> PLOT_FRAME" procedure to plot the axes and use the NOFRAME option of PLOT_BARCHART. This option can also be used to superimpose several charts. The width of the bars can be adjusted with the "-> graphics -> BARCHART-WIDTH" graphics command. This is useful when overlaying several charts, as shown in the example. The procedure leaves the plot open for further additions, the "-> Call -> PLOT_END" procedure should be called when the plot is complete. Format: !W
  CALL PLOT_BARCHART("-> Call -> PLOT_BARCHART -> x", "-> Call -> PLOT_BARCHART -> y" [, "-> Call -> PLOT_BARCHART -> x_label" [, "-> Call -> PLOT_BARCHART -> y_label" [, "-> Call -> PLOT_BARCHART -> title" [, "-> Call -> PLOT_BARCHART -> options"]]]])
!W
Example: !W
  !"-> graphics -> colour" red red 1 blue 0 green 0
  !col blue red 0 blue 1 green 0
  !"-> graphics -> representation" barchart-1 fill-area-colour blue fill-area-int-style solid
  !rep "-> graphics -> REPRESENTATION -> item -> barchart-2" fill-area-colour red fill-area-int-style solid

  "-> Global" x="-> algebra -> functions -> row"(20)/3
  Global y="-> algebra -> functions -> sin"(x)
  Global z="-> algebra -> functions -> cos"(x)
  !"-> graphics -> barchart-width" 0.9
  Call plot_barchart(x,y,`x`,`f(x)`,`sin(x) and cos(x)`)
  !bar-w 0.7
  Call plot_barchart(x,z,``,``,``,`noframe`)
  Call "-> Call -> plot_end"
!W
This example shows 2 overlaid bar charts, distinguished by colour. 3 x A "-> algebra -> variables -> types -> Matrix" which contains the ordinates of the bars to be plotted. This argument does not have to be 1-dimensional - the structure of the argument matrix is ignored - but the overall length has to be the same as that of the coordinate vector "-> Call -> PLOT_BARCHART -> y". [This argument is mandatory. No default is supplied.] 3 y A "-> algebra -> variables -> types -> Matrix" which contains the coordinates of the bars to be plotted. This argument does not have to be 1-dimensional - the structure of the argument matrix is ignored - but the overall length has to be the same as that of the ordinate vector "-> Call -> PLOT_BARCHART -> x". [This argument is mandatory. No default is supplied.] 3 x_label The "-> algebra -> variables -> types -> String" that should appear along the horizontal axis. The label is shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". If omitted or if specified as `*`, the name of the global variable associated with the ordinate vector "-> Call -> PLOT_BARCHART -> x" will be used, unless this vector is the result of an operation, in which case the string `Ordinate` will be shown. This argument is ignored if the NOFRAME option is in effect. 3 y_label The "-> algebra -> variables -> types -> String" that should appear along the vertical axis. The label is shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". If omitted or if specified as `*`, the name of the global variable associated with the coordinate vector "-> Call -> PLOT_BARCHART -> y" will be used, unless this vector is the result of an operation, in which case the string `Coordinate` will be shown. This argument is ignored if the NOFRAME option is in effect. 3 title This should be a "-> algebra -> variables -> types -> String" that contains the title that you want to appear at the top of the plot. The title is shown using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". If omitted or if specified as `*`, a name will be constructed from the global variables from which the plot is made. If one of these is the result of an operation, then the string `Title` will be used. This argument is ignored if the NOFRAME option is in effect. 3 options A "-> algebra -> variables -> types -> String" which can contain the following options: !Wtable_start !T+P + + . ------------------------------------------------------------- Option Effect Notes ------------------------------------------------------------- FRAME Plots the bar chart with a frame Default NOFRAME Reuses the existing frame Not default ------------------------------------------------------------- !Wtable_end 3 representations The first histogram in a frame is drawn using the "-> graphics -> REPRESENTATION -> item -> BARCHART-1" representation, the 2nd using "-> graphics -> REPRESENTATION -> item -> BARCHART-2", the third with "-> graphics -> REPRESENTATION -> item -> BARCHART-3" etc. The counter is reset each time a plot is started or completed. 2 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: !W
  CALL PLOT_COMMENT(place, text)
!W
Example: !W
  Call "-> Call -> plot_frame"(1,1,2,2,`x`,`y`,`Title`)
  Call plot_comment(`up-left`,`Made on `/"-> algebra -> variables -> predefined -> machine")
  Call plot_comment('down-right`,`Time left: `/"-> algebra -> functions -> string"("-> algebra -> variables -> predefined -> time_left"))
  Call "-> Call -> plot_end"
!W
Will place a comment string on the left in the top row that reads (on a Vax) "Made on Vax". 3 place The location should be given as a single "-> algebra -> variables -> types -> String" in the format: !W
  `h-v`
!W
Where !W
  h = LEFT or RIGHT
  v = UP or DOWN
!W
3 text The "-> algebra -> variables -> types -> String" to be plotted. This string can be up to 80 characters long but shorter strings are recommended so as to avoid overflow of the comment areas on the left into those on the right. The comment string is plotted with the text representation "-> graphics -> REPRESENTATION -> item -> COMMENT". 2 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: !W
  CALL PLOT_CONTOURS("-> Call -> PLOT_CONTOURS -> matrix" [, "-> Call -> PLOT_CONTOURS -> n_contours" [, "-> Call -> PLOT_CONTOURS -> options" ...
       [, "-> Call -> PLOT_CONTOURS -> x-vector" [, "-> Call -> PLOT_CONTOURS -> y-vector" ...
       [, "-> Call -> PLOT_CONTOURS -> x-label" [, "-> Call -> PLOT_CONTOURS -> y-label" [, "-> Call -> PLOT_CONTOURS -> title" ]]]]]]])
!W
Example: !W
  Call "-> Call -> book_matrix"(a,30,30)
  Call plot_contours(a)
!W
3 matrix The "-> algebra -> variables -> types -> 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). 3 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]. 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. !Wtable_start !T+P + + . --------------------------------------------------------------------------- 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 --------------------------------------------------------------------------- !Wtable_end 3 x-vector A 1-dimensional "-> algebra -> variables -> types -> Matrix" with the x-coordinates of the matrix that is to be plotted. 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. 3 y-vector A 1-dimensional "-> algebra -> variables -> types -> Matrix" with the y-coordinates of the matrix that is to be plotted. 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. 3 x-label A "-> algebra -> variables -> types -> String" to be placed along the x-axis. This label will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". 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. 3 y-label A "-> algebra -> variables -> types -> String" to be placed along the y-axis. This label will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". 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. 3 title A "-> algebra -> variables -> types -> String" to be placed above the plot. The title will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". If omitted, the name of the global variable associated with matrix is used, if there is one, otherwise the title is left blank. 2 PLOT_DRIFT_AREA Plots, using the current projection, the part of the chamber that falls within the drift "-> &DRIFT -> AREA". The plot frame is left open after the call for further additions. Once the plot is complete, "-> Call -> PLOT_END" should be called to close the plot frame. Use "-> Call -> PLOT_FIELD_AREA" to plot the field area. Format: !W
  CALL PLOT_DRIFT_AREA(["-> Call -> PLOT_DRIFT_AREA -> title"])
!W
Example: !W
  "-> &DRIFT -> area" -1 -1 -2 1 1 2 view x+2*y+3*z=5
  Call plot_drift_area
!W
3 title An optional "-> algebra -> variables -> types -> String" to placed at the top of the figure. The title will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". If omitted, the "-> &CELL -> CELL-IDENTIFIER" is used provided the latter is not blank. If the cell identifier is blank, then the title will be `Layout of the cell`. 2 PLOT_DRIFT_LINE Plots a projection of the current drift-line. The desired projection should be set on beforehand with the "-> &DRIFT -> AREA" command and coordinate axes should have been plotted before, with e.g. "-> Call -> PLOT_DRIFT_AREA". Format: !W
  CALL PLOT_DRIFT_LINE
!W
Example: !W
  "-> Global" x0=0.001
  Global y0=0.028
  Call "-> Call -> plot_drift_area"
  For i From 1 To 50 Do
     Call "-> Call -> drift_mc_electron"(x0, y0, 0, status, time)
     Call plot_drift_line
  Enddo
  Call "-> Call -> plot_end"
!W
This examples makes a plot of 50 Monte Carlo integrated drift-lines all starting from the same point (x0,y0). One would use a similar construction to histogram e.g. the drift time or the arrival point. 3 representations If the current drift-line is for an electron, then it will be plotted using the "-> graphics -> REPRESENTATION -> item -> E-DRIFT-LINE" polyline representation. Ion drift-lines are plotted using the "-> graphics -> REPRESENTATION -> item -> ION-DRIFT-LINE" polyline representation. 2 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 "-> graphics -> OPTIONS -> WAIT-AFTER-PLOT" option is in effect, a prompt is displayed before proceeding with the next plot. You 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: !W
  CALL PLOT_END( [string] )
!W
2 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 "-> Call -> PLOT_ERROR_BAR". Format: !W
  CALL PLOT_ERROR_BAND(x, y1, y2)
!W
Example: !W
  Call "-> Call -> plot_frame"(0,0,5,5,`x`,`y`,`title`)
  "-> Global" x1=("-> algebra -> functions -> row"(51)-1)/10
  Global y1=1+x1^2/10
  Global y2=y1*1.2
  Call plot_error_band(x1,y1,y2)
  Call "-> Call -> plot_end"
!W
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. 3 vectors Each of the 3 argument should be a 1-dimensional "-> algebra -> variables -> types -> 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. 3 representations The area is filled with a colour according to fill area representation "-> graphics -> REPRESENTATION -> item -> 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. 2 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: !W
  CALL PLOT_ERROR_BAR(x, y [, ex-, ey- [, ex+, ey+]] [, "-> Call -> PLOT_ERROR_BAR -> type" [, "-> Call -> PLOT_ERROR_BAR -> size"]])
!W
Example: !W
  "-> 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 "-> Call -> plot_frame"(0,0,5,5,`x`,`y`,`title`)
  Call plot_error_bar(x,y,ex1,ey1,`circle`,0.02)
  Call plot_error_bar(x+2,y,ex1,ey1,ex2,ey2,`square`)
  Call "-> Call -> plot_end"
!W
3 centre Each of the coordinates of the centre (x,y) of the error bar can be of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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.] 3 errors Lengths of the error bars, measured outwards from the centre of the symbol. Error bars normally have positive values. If they are negative however,then they will appear on the opposite side: a negative "left" error bar will e.g. be plotted on the right of the symbol. 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 "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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.] 3 type The following error bar types are currently available: !W
!W !W
!W

!Wdl_start !T+ + ------------------------------------------------------------------- Type Description ------------------------------------------------------------------- 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. ------------------------------------------------------------------- !Wdl_end More error bar types can be added on request. [The default error bar type is CIRCLE.] 3 representations All error bars contain line segments, which are drawn according to the polyline representation "-> graphics -> REPRESENTATION -> item -> 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 "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> HOLLOW" one gets "empty" markers, while "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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. 3 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.] 2 PLOT_FIELD_AREA Plots, using the current projection, the part of the chamber that falls within the field "-> &FIELD -> AREA". The plot frame is left open after the call for further additions. Once the plot is complete, "-> Call -> PLOT_END" should be called to close the plot frame. Use "-> Call -> PLOT_DRIFT_AREA" to plot the drift area. Format: !W

  CALL PLOT_FIELD_AREA(["-> Call -> PLOT_FIELD_AREA -> title"])
!W
Example: !W
  "-> &FIELD -> area" -1 -1 -2 1 1 2 view x+2*y+3*z=5 cut
  Call plot_field_area
!W
3 title The title to be given to the plot. The title will be plotted using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". This argument is optional. If present, it should be of type "-> algebra -> variables -> types -> String". If omitted, the "-> &CELL -> CELL-IDENTIFIER" is used provided the latter is not blank. If the cell identifier is blank, then the title will be `Layout of the cell`. 2 PLOT_FRAME Draws a set of Cartesian coordinate axes with labels. Call "-> Call -> PLOT_END" to end the plot. Format: !W
  CALL PLOT_FRAME("-> Call -> PLOT_FRAME -> xmin", "-> Call -> PLOT_FRAME -> ymin", "-> Call -> PLOT_FRAME -> xmax", "-> Call -> PLOT_FRAME -> ymax" ...
       [, "-> Call -> PLOT_FRAME -> x_label" [, "-> Call -> PLOT_FRAME -> y_label" [, "-> Call -> PLOT_FRAME -> title"]]])
!W
3 xmin The lower x limit of the frame. This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> Number". [A mandatory parameter, no default.] 3 ymin The lower y limit of the frame. This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> Number". [A mandatory parameter, no default.] 3 xmax The upper x limit of the frame. This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> Number". [A mandatory parameter, no default.] 3 ymax The upper y limit of the frame. This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> Number". [A mandatory parameter, no default.] 3 x_label The label to be placed along the x-axis. This label will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> String". [By default: `x`] 3 y_label The label to be placed along the y-axis. This label will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> String". [By default: `y`] 3 title The label to be placed along the top of the screen. This label will be shown using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". This argument is should be a variable, constant or expression that evaluates to a "-> algebra -> variables -> types -> String". [By default left empty.] 2 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 "-> Call -> 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. "-> Call -> PLOT_END" should be called to end the plot. Format: !W
  CALL PLOT_GRAPH(x_"-> Call -> PLOT_GRAPH -> vector", y_vector [, x_"-> Call -> PLOT_GRAPH -> label" [, y_label, [,"-> Call -> PLOT_GRAPH -> title"]]])
!W
Example: !W
  "-> Global" n=20
  Call "-> Call -> book_matrix"(x,n)
  Call "-> Call -> book_matrix"(y,n)
  Global m=3
  For i From 1 To n Do
     Global x[i]="-> algebra -> functions -> cos"(m*2*pi*i/(n-1))
     Global y[i]="-> algebra -> functions -> sin"(m*2*pi*i/(n-1))
  Enddo
  Call plot_graph(x,y)
  !"-> graphics -> representation" circle polymarker-colour green
  Call "-> Call -> plot_markers"(x,y,`circle`)
  Call "-> Call -> plot_end"
!W
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. 3 vector The arguments x_vector and y_vector should both be of type "-> algebra -> variables -> types -> 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 unravelled. Use the "-> Call -> PLOT_CONTOURS" and "-> Call -> PLOT_SURFACE" procedures if you wish to plot 2-dimensional matrices. [These arguments are mandatory. No default is supplied.] 3 label The x- and y-axis labels should be specified as "-> algebra -> variables -> types -> 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. 3 title The title is a "-> algebra -> variables -> types -> String" variable. [The title is left blank if omitted.] 3 representations The curve is drawn with polyline representation "-> graphics -> REPRESENTATION -> item -> FUNCTION-1". The labels are shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". The title is shown using the text representation "-> graphics -> REPRESENTATION -> item -> TITLE". 2 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 autorange 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 histogram. If you wish to control the axes yourself, then use the "-> Call -> 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 "-> Call -> PLOT_END" procedure should be called when the plot is complete. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the histogram has been plotted and to False if it hasn't. OK is set to True even if the range has not yet been established. Format: !W
  CALL PLOT_HISTOGRAM("-> Call -> PLOT_HISTOGRAM -> histogram" [, "-> Call -> PLOT_HISTOGRAM -> x_label" [, "-> Call -> PLOT_HISTOGRAM -> title" [, "-> Call -> PLOT_HISTOGRAM -> options"]]])
!W
Example: !W
  !"-> graphics -> colour" red red 1 blue 0 green 0
  !col blue red 0 blue 1 green 0
  !col green red 0 blue 0 green 1
  !"-> graphics -> representation" histogram-1 polyline-colour green
  !rep "-> graphics -> REPRESENTATION -> item -> histogram-2" polyline-colour red
  !rep "-> graphics -> REPRESENTATION -> item -> histogram-3" polyline-colour blue
  Call plot_histogram(all_1,`Time [microsec]`,`Arrival time spectrum`)
  Call plot_histogram(sel_1,` `,` `,`noframe`)
  Call plot_histogram(sel_2,` `,` `,`noframe`)
  Call "-> Call -> plot_end"
!W
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 distinguished by colour. 3 histogram The "-> algebra -> variables -> types -> Histogram" is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or to "-> Call -> GET_HISTOGRAM". [This argument is mandatory. No default is supplied.] 3 x_label The "-> algebra -> variables -> types -> String" that should appear along the horizontal axis. The label is shown using the text representation "-> graphics -> REPRESENTATION -> item -> LABELS". This argument is ignored if the NOFRAME option is in effect. [By default, this will be `Coordinate`] 3 title This should be a "-> algebra -> variables -> types -> String" that contains the title that you want to appear at the top of the plot. The title is shown using the text representation "-> graphics -> REPRESENTATION -> item -> 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. This argument is ignored if the NOFRAME option is in effect. 3 options A "-> algebra -> variables -> types -> String" which can contain the following options: !Wtable_start !T+P + + . ------------------------------------------------------------- Option Effect Notes ------------------------------------------------------------- FRAME Plots the histogram with a frame Default NOFRAME Reuses the existing frame Not default ------------------------------------------------------------- !Wtable_end 3 representations The first histogram in a frame is drawn using the "-> graphics -> REPRESENTATION -> item -> HISTOGRAM-1" representation, the 2nd using "-> graphics -> REPRESENTATION -> item -> HISTOGRAM-2", the third with "-> graphics -> REPRESENTATION -> item -> HISTOGRAM-3" etc. The counter is reset each time a plot is started or completed. Use the "-> Call -> SKIP_HISTOGRAM" procedure if you wish to skip one or more representations from this sequence. 2 PLOT_LINE Connects a series of points either by straight line segments, or by a cubic spline. This procedure should only be called after a call to "-> Call -> PLOT_FRAME". If you wish to make a graph, then using the "-> Call -> PLOT_GRAPH" procedure is probably simpler. If the curve you wish to plot is in fact a projection of a line in 3 dimensions, then consider using "-> Call -> PROJECT_LINE". Two formats are accepted: one takes a series of (x,y) coordinates, the other takes a pair of vectors as arguments. Formats: !W
  CALL PLOT_LINE("-> Call -> PLOT_LINE -> x"1, "-> Call -> PLOT_LINE -> y"1, x2, y2, ..., x_n, y_n [, "-> Call -> PLOT_LINE -> option"])
  CALL PLOT_LINE("-> Call -> PLOT_LINE -> x_vector", "-> Call -> PLOT_LINE -> y_vector" [, option])
!W
Example 1: !W
  !"-> graphics -> colour" cyan red 0 green 1 blue 1
  !"-> graphics -> representation" "-> graphics -> REPRESENTATION -> item -> function-4" polyline-colour cyan
  Call "-> Call -> plot_frame"(-1,-1,2,2)
  Call plot_line(0,0, 1,0, 0,1, 1,1, 0,0, `"-> graphics -> REPRESENTATION -> item -> function-4"`)
  Call "-> Call -> plot_end"
!W
A colour called CYAN is defined with the "-> graphics -> COLOUR" graphics command. Tis colour is used to modify the appearance of "-> graphics -> REPRESENTATION -> item -> FUNCTION-4", polylines. This polyline representation is used to produce a figure. Example 2: !W
  "-> Global" time="-> algebra -> functions -> row"(20)
  Call "-> Call -> plot_frame"(0,-1.1,21,1.1,`Time`,`Sinus`,`A curve`)
  Call plot_line(time,"-> algebra -> functions -> sin"(time/3),`"-> graphics -> REPRESENTATION -> item -> FUNCTION-1"`)
  Call "-> Call -> plot_end"
!W
This example shows how one can plot a simple curve: the vector TIME is declared and initialised with the numbers 1 through 20 using the "-> algebra -> functions -> ROW" function. Then, a plot is made of TIME vs sin(TIME/3). A slightly simpler way to achieve this result would have been to use "-> Call -> PLOT_GRAPH". Example 3: !W
  "-> Global" r=0.2
  Global phi=2*pi*"-> algebra -> functions -> row"(21)/20
  Call plot_line(r*"-> algebra -> functions -> cos"(phi),r*"-> algebra -> functions -> sin"(phi),`"-> graphics -> REPRESENTATION -> item -> FUNCTION-1"`)
!W
Plots a circle. 3 x One of the 2 formats of the PLOT_LINE procedure call, takes a series of (x,y) coordinates as argument to describe the line which is to be drawn. Each of the x and y coordinates should be of the type "-> algebra -> variables -> types -> Number". There should be at least 2 pairs of (x,y) coordinates if you use this format. The vector and scalar formats can not be mixed. [These are mandatory arguments, no default is supplied.] 3 y See "-> Call -> PLOT_LINE -> x". 3 x_vector One of the 2 formats of the PLOT_LINE procedure call, takes a pair of (x,y) coordinate vectors as argument. These vectors should both be a 1-dimensional "-> algebra -> variables -> types -> Matrix". The vectors must have an equal length of at least 2. The vector and scalar formats can not be mixed. [These are mandatory arguments, no default is supplied.] 3 y_vector See "-> Call -> PLOT_LINE -> x_vector". 3 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: "-> graphics -> REPRESENTATION -> item -> SOLID", "-> graphics -> REPRESENTATION -> item -> DASHED", "-> graphics -> REPRESENTATION -> item -> DOTTED", "-> graphics -> REPRESENTATION -> item -> DASH-DOTTED", "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", "-> graphics -> REPRESENTATION -> item -> FUNCTION-2", "-> graphics -> REPRESENTATION -> item -> FUNCTION-3", "-> graphics -> REPRESENTATION -> item -> FUNCTION-4", "-> graphics -> REPRESENTATION -> item -> FUNCTION-5", "-> graphics -> REPRESENTATION -> item -> FUNCTION-6", "-> graphics -> REPRESENTATION -> item -> FUNCTION-7", "-> graphics -> REPRESENTATION -> item -> COMMENT", "-> graphics -> REPRESENTATION -> item -> ERROR-BAR" and "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS". Use the "-> graphics -> REPRESENTATION" graphics command to adjust the line width, the line type and the colour. 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.] 2 PLOT_MARKERS Plots a series of markers. This procedure should only be called after a call to "-> Call -> PLOT_FRAME". If the markers you wish to plot are in fact located in 3-dimensional space, then consider using "-> Call -> PROJECT_MARKERS". Formats: !W
  CALL PLOT_MARKERS(x1, y1, x2, y2, x3, y3, ... [, "-> Call -> PLOT_MARKERS -> marker_type"])
  CALL PLOT_MARKERS(x_vector, y_vector [, marker_type])
!W
Example: !W
  "-> Global" n=50
  Call "-> Call -> book_matrix"(x,n)
  Call "-> Call -> book_matrix"(y,n)
  For i From 1 To n Do
     Global x[i]=i
     Global y[i]="-> algebra -> functions -> rnd_gauss"
  Enddo
  Call "-> Call -> plot_frame"("-> algebra -> functions -> number"(x[1]),-3,"-> algebra -> functions -> number"(x[n]),3,...
     `Time`,`Random`,`Scattered points`)
  !"-> graphics -> representation" circle polymarker-colour orange
  Call plot_markers(x,y,`CIRCLE`)
  Call "-> Call -> plot_end"
!W
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. 3 coordinates This procedure can be used both with a series of (x, y) pairs as arguments, and with a single pair of 1-dimensional matrices. If you supply (x,y) pairs, then the arguments must be of type "-> algebra -> variables -> types -> Number", otherwise they should be of type "-> algebra -> variables -> types -> Matrix". [These are mandatory arguments, no default is supplied.] 3 marker_type The kind of marker to be used. This is a argument of type "-> algebra -> variables -> types -> String" that refers to a graphics representation. Examples in the standard graphics representation tables are "-> graphics -> REPRESENTATION -> item -> CROSS", "-> graphics -> REPRESENTATION -> item -> DOT", "-> graphics -> REPRESENTATION -> item -> PLUS" and "-> graphics -> REPRESENTATION -> item -> CIRCLE". Use the "-> graphics -> REPRESENTATION" graphics command to adjust the size of the marker, the colour and the marker type. Please note that other marker types are available with the "-> Call -> 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_MARKERS. [By default, the CIRCLE representation will be used.] 2 PLOT_OBLIQUE_ERROR_BAR Plots a series of oblique error bars. The format and collection of symbols is identical to that of "-> Call -> PLOT_ERROR_BAR", but the appearance differs. This procedure plots a symbol and a single oblique error bar from !W
  (x - ex\-\, y - ey\-\) - (x + ex\+\, y + ey\+\)
!W
Format: !W
  CALL PLOT_OBLIQUE_ERROR_BAR(x, y [, ex-, ey- [, ex+, ey+]] [, type [, size]])
!W
2 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: !W
  CALL PLOT_START
!W
Example: !W
  // Start graphics
  Call plot_start

  // Set a viewport for normalisation transformation 1 and show the border
  Call "-> Call -> GKS_viewport"(1, 0.25, 0.75,  0.25, 0.75)
  Call "-> Call -> GKS_select_nt"(0)
  Call "-> Call -> plot_line"(0.25,0.25, 0.25,0.75, 0.75,0.75, 0.75,0.25, 0.25,0.25, `"-> graphics -> REPRESENTATION -> item -> box-tickmarks"`)

  // Set a window for normalisation transformation 1 and select it
  Call "-> Call -> GKS_window"  (1, 0,    2,    -1,    3)
  Call "-> Call -> GKS_select_nt"(1)

  // Plot some elements
  Call "-> Call -> plot_line"(0,0,1,1,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_markers"(0,0,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
  Call "-> Call -> plot_text"(1,1,`abc`,`"-> graphics -> REPRESENTATION -> item -> function-3"`)

  // Close the plot
  Call "-> Call -> plot_end"
!W
2 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: !W
  CALL PLOT_SURFACE("-> Call -> PLOT_SURFACE -> matrix" ...
       [, "-> Call -> PLOT_SURFACE -> \θ" [, "-> Call -> PLOT_SURFACE -> \φ" ...
       [, "-> Call -> PLOT_SURFACE -> x-vector" [, "-> Call -> PLOT_SURFACE -> y-vector" ...
       [, "-> Call -> PLOT_SURFACE -> x-label" [, "-> Call -> PLOT_SURFACE -> y-label" [, "-> Call -> PLOT_SURFACE -> title"]]]]]]])
!W
Example: !W
  Call "-> Call -> book_matrix"(a,30,30)
  Call plot_surface(a)
!W
3 matrix The "-> algebra -> variables -> types -> 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). The ordinates of the matrix have to be equidistant because of limitations in the underlying graphics packages. 3 \θ Polar viewing angle, in degrees. This argument is of type "-> algebra -> variables -> types -> Number". Default: 60\°. 3 \φ Azimuthal viewing angle, in degrees. This argument is of type "-> algebra -> variables -> types -> Number". Default: 60\°. 3 x-vector A 1-dimensional "-> algebra -> variables -> types -> Matrix" with the x-coordinates of the matrix that is to be plotted. Only the first and last element are used to set the scale along the x-axis of the plot. Hence, a function value matrix with non-equidistant ordinates will not be rendered correctly. 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. 3 y-vector A 1-dimensional "-> algebra -> variables -> types -> Matrix" with the y-coordinates of the matrix that is to be plotted. Only the first and last element are used to set the scale along the y-axis of the plot. Hence, a function value matrix with non-equidistant ordinates will not be rendered correctly. 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. 3 x-label A "-> algebra -> variables -> types -> 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. The label is shown using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation. 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. 3 y-label A "-> algebra -> variables -> types -> 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. The label is shown using the "-> graphics -> REPRESENTATION -> item -> LABELS" text representation. 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. 3 title A "-> algebra -> variables -> types -> String" to be placed above the plot. The title is shown using the "-> graphics -> REPRESENTATION -> item -> TITLE" text representation. If omitted, the name of the global variable associated with matrix is used, if there is one, otherwise the title is left blank. 2 PLOT_TEXT Plots a string in the frame that should previously have been opened with "-> Call -> PLOT_FRAME". The text string is plotted near the point ("-> Call -> PLOT_TEXT -> x","-> Call -> PLOT_TEXT -> y"). Whether this point is the centre of the box enclosing the string, the lower left corner, or the middle of the upper edge etc. is determined by the "-> Call -> PLOT_TEXT -> alignment". The "-> Call -> PLOT_TEXT -> orientation" of the string will by default be horizontal. The appearance of the text string is determined by the "-> Call -> PLOT_TEXT -> representation" which is used. Provided the graphics option "-> graphics -> OPTIONS -> DISPLAY-CONTROL-CHARACTERS" is on, which is by default the case, special symbols are available with some graphics system through the following mechanisms: !Wol_start a. Where enclosed by squared brackets, the strings 'cm2', 'cm3', 'micron', 'microsec' and 'microamp' are shown in their conventional form: super-script 2 for 'cm2', Greek mu for 'micron' etc. b. 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 super-scripts to indicate the charge and sub-scripts showing the number of atoms per molecule. c. Most Greek letters, diacritics and ligatures are accessible as SGML "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> HIGZ -> entities", e.g. &Ksi; é and ß. d. Super-script and sub-script can be produced using SGML "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> HIGZ -> tags", e.g. 55Fe and CH3-O-CH3 (dimethylether). !Wol_end Format: !W
  CALL PLOT_TEXT(x, y, string [, "-> Call -> PLOT_TEXT -> representation" [, "-> Call -> PLOT_TEXT -> alignment" [, "-> Call -> PLOT_TEXT -> orientation"]]])
!W
Example: !W
  Call plot_text(0.5, 0.5, `Some text`, `TIMES-ROMAN`, `LEFT-BASE`)
!W
The string "Some text" will be plotted horizontally with its lower left corner at (0.5,0.5). 3 x The x-coordinate of the place near which the string is to be plotted. Which part of the string is located at (x,y) is determined by the "-> Call -> PLOT_TEXT -> alignment". This argument is mandatory and should be of type "-> algebra -> variables -> types -> Number". 3 y The y-coordinate of the place near which the string is to be plotted. Which part of the string is located at (x,y) is determined by the "-> Call -> PLOT_TEXT -> alignment". This argument is mandatory and should be of type "-> algebra -> variables -> types -> Number". 3 representation Any of the text representations that are currently defined. These include representations that are reserved for elements of graphs (such as "-> graphics -> REPRESENTATION -> item -> TITLE") as well as some general purpose representations such as "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" etc. For convenience, a few text representations are provided that are not used by the program and that can therefore be modified at will. These include some commonly used fonts: Times Roman ("-> graphics -> REPRESENTATION -> item -> TIMES-ROMAN") and Prestige Elite ("-> graphics -> REPRESENTATION -> item -> PRESTIGE"), but also Greek characters ("-> graphics -> REPRESENTATION -> item -> GREEK"), gothic characters ("-> graphics -> REPRESENTATION -> item -> GOTHIC") and the italics for most of these (e.g. "-> graphics -> REPRESENTATION -> item -> GOTHIC-ITALIC"). Not all of these are available with all graphics systems. The font should be specified with a variable of the type "-> algebra -> variables -> types -> String". [By default, the "-> graphics -> REPRESENTATION -> item -> COMMENT" text representation is used.] 3 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 "-> algebra -> variables -> types -> String" in the format `h-v` where h is one of the horizontal and v one of the vertical "-> Call -> GKS_SET_TEXT_ALIGNMENT -> alignments". [By default, the alignment is assumed to be `NORMAL-NORMAL`.] 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 "-> algebra -> variables -> types -> Number" and should be specified in degrees. [By default: 0\°.] 2 PLOT_TITLE Plots a text "-> algebra -> variables -> types -> String" in the area reserved for the title of the plot. This procedure is used if you wish to replace the default title of a plot with your own. The title is shown according to the "-> graphics -> REPRESENTATION -> item -> TITLE" representation. The location is determined with the "-> graphics -> LAYOUT" command. Format: !W
  CALL PLOT_TITLE(title)
!W
Example: !W
  !"-> graphics -> representation" "-> graphics -> REPRESENTATION -> item -> title" text-colour background
  "-> &DRIFT -> drift" track
  !rep "-> graphics -> REPRESENTATION -> item -> title" text-colour red
  Call plot_title(`Track at 1 m from the membrane`)
  Call "-> Call -> plot_end"
!W
To make the default title invisible, the text colour of the title is set to BACKGROUND before the drift-line plot is made. Once this plot is finished, the title colour is restored and a new title is put in place. The PLOT_END procedure is used to close the graph. 2 PLOT_TRACK This procedure plots a projection of the track according to the current settings of the "-> &DRIFT -> AREA" command of the drift section. The "-> Call -> PLOT_DRIFT_AREA" procedure should be called before invoking PLOT_TRACK and "-> Call -> 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 "-> Call -> NEW_TRACK" and then at least once "-> Call -> GET_CLUSTER", even if you don't use the data returned by the latter procedure. Format: !W
  CALL PLOT_TRACK
!W
Example: !W
  For i From 1 To nstat Do
     If i=10*entier(i/10) Then Say "Iteration {i}"
     Call "-> Call -> plot_drift_area"
     Call "-> Call -> new_track"
     "-> Do"
        Call "-> Call -> get_cluster"(xcls,ycls,zcls,npair,done)
        If done Then
           "-> Do -> Leave"
        Else
           For n From 1 To npair Do
             Call "-> Call -> drift_mc_electron"(xcls, ycls, zcls, status, time)
             Call "-> Call -> plot_drift_line"
           Enddo
        Endif
     Enddo
     Call plot_track
     Call "-> Call -> plot_end"
  Enddo
!W
(This example shows how one can make the same kind of plot as DRIFT TRACK by calling procedures.) 3 representations The "-> &DRIFT -> TRACK -> representations" used for showing the track are explained under "-> &DRIFT -> TRACK". 2 PLOT_X_LABEL Plots a text "-> algebra -> variables -> types -> String" in the area reserved for the label along the x-axis of the plot. This procedure is used if you wish to replace the default label of a plot with your own. The label is shown according to the "-> graphics -> REPRESENTATION -> item -> LABELS" representation. The location is determined with the "-> graphics -> LAYOUT" command. Format: !W
  CALL PLOT_X_LABEL(label)
!W
Example: See "-> Call -> PLOT_TITLE" 2 PLOT_Y_LABEL Plots a text "-> algebra -> variables -> types -> String" in the area reserved for the label along the y-axis of the plot. This procedure is used if you wish to replace the default label of a plot with your own. The label is shown according to the "-> graphics -> REPRESENTATION -> item -> LABELS" representation. The location is determined with the "-> graphics -> LAYOUT" command. Format: !W
  CALL PLOT_Y_LABEL(label)
!W
Example: See "-> Call -> PLOT_TITLE" 2 POLAR_TO_CARTESIAN Converts polar (r,\φ) coordinates to Cartesian (x,y) coordinates. The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL POLAR_TO_CARTESIAN(r,\φ,x,y)
!W
2 POLAR_TO_INTERNAL Converts polar (r,\φ) coordinates to (\ρ,\φ') coordinates that are used internally when dealing with cells in polar coordinates. The internal coordinates a conformal mapping of (x,y) coordinates. If the condition r>0 is not met, then the global variable "-> algebra -> variables -> predefined -> OK" is set to False, otherwise to True. Internal coordinates are related to polar coordinates by: !W
  \ρ  = log(r)     [dimension not defined]
  \φ' = \π \φ/180    [radians]
!W
The input arguments of this procedure can be either of type "-> algebra -> variables -> types -> Number" or of type "-> algebra -> variables -> types -> 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: !W
  CALL POLAR_TO_INTERNAL(r,\φ,\ρ,\φ')
!W
2 PREPARE_RND_FUNCTION Establishes the expression according to which the "-> algebra -> functions -> 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 "-> algebra -> functions -> RND_HISTOGRAM" function should be used. !D1 RND_FUNCTION is based on the FUNLUX routine from the CERN program library. !WRND_FUNCTION is based on the !WFUNLUX !Wroutine from the CERN program library. Format: !W
  CALL PREPARE_RND_FUNCTION("-> Call -> PREPARE_RND_FUNCTION -> function", min, max)
!W
Example: !W
  Call "-> 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 "-> Call -> fill_histogram"(hist,rnd_function)
  Enddo
  Call "-> Call -> plot_histogram"(hist)
  Call "-> Call -> plot_end"
!W
3 function This argument, of type "-> algebra -> variables -> types -> 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 "-> algebra -> functions -> 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.] 3 range With xmin and xmax, you indicate the smallest and largest random number that RND_FUNCTION will generate. Both are "-> algebra -> variables -> types -> Number"s. [No default, these arguments are mandatory.] 2 PRINT The PRINT procedure simply prints the arguments it is given. Format: !W
  CALL PRINT(any number of arguments)
!W
2 PRINT_DRIFT_LINE Prints the current drift-line. Format: !W
  CALL PRINT_DRIFT_LINE
!W
Example: !W
  Call "-> Call -> drift_electron"(1,2)
  Call print_drift_line
!W
2 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: !W
  CALL PRINT_HISTOGRAM("-> Call -> PRINT_HISTOGRAM -> reference" [, x-title [, title]])
!W
3 reference The histogram is referenced via a global variable that has usually been returned by a call to "-> Call -> BOOK_HISTOGRAM" or to "-> Call -> GET_HISTOGRAM". You may also supply an expression that evaluates to an "-> algebra -> variables -> types -> Histogram". 2 PRINT_MATRIX Prints one or more variables of type "-> algebra -> variables -> types -> Matrix". Format: !W
  CALL PRINT_MATRIX(matrix_1, matrix2, ...)
!W
Example: !W
  Call "-> Call -> book_matrix"(a,2,3)
  Call print_matrix(a)
!W
A matrix called A is booked, and is then immediately printed. This shows how matrices are initialised. 2 PROJECT_LINE Projects a line onto the viewing "-> &FIELD -> AREA -> plane" that has been chosen with the "-> &FIELD -> AREA" statement. The procedure should be only be called after a plot frame has been opened, e.g. with "-> Call -> PLOT_FIELD_AREA" or "-> Call -> PLOT_DRIFT_AREA". Format: !W
  CALL PROJECT_LINE("-> Call -> PROJECT_LINE -> vector"_1, vector_2, vector_3 [, "-> Call -> PROJECT_LINE -> representation"])
!W
Example: !W
  "-> &DRIFT"
  "-> Global" n=20
  Global nmax=5000
  Call "-> Call -> delete_matrix"
  Call "-> Call -> book_matrix"(xbuf,nmax)
  Call "-> Call -> book_matrix"(ybuf,nmax)
  Call "-> Call -> book_matrix"(zbuf,nmax)
  Call "-> Call -> book_matrix"(nbuf,n)
  Call "-> 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 "-> Call -> drift_electron_3"(-0.5,y,1.5,status,time)
     Call "-> Call -> get_drift_line"(xd,yd,zd,t)
     Call "-> Call -> drift_information"(`steps`,nd)
     If i0+nd>nmax Then
        Say "Buffer overflow, reducing n to {i-1}."
        Global n=i-1
        "-> Do -> Leave"
     Endif
     Call "-> 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 "-> algebra -> functions -> type"(a)=`Undefined` Then
         "-> Do -> Leave"
     Elseif type(a)#`Number` | type(b)#`Number` | type(c)#`Number` Then
         Say "The vector is not fully numeric"
         "-> Do -> Iterate"
     Endif
     "-> &DRIFT -> area" -1.5 -1.5 -1.5 4.5 4.5 4.5 view {a}*x+{b}*y+{c}*z=0 3d
     Call "-> Call -> plot_drift_area"
     For i From 1 Step 1 To n Do
        Call "-> Call -> book_matrix"(ind,nbuf[i])
        Global i0="-> algebra -> functions -> 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 "-> Call -> plot_end"
  Enddo
!W
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. 3 vector 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 "-> algebra -> variables -> types -> Matrix". 3 representation The polyline representation that you wish to use for plotting the line. Usually, this would be "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" etc, but you can also use e.g. "-> graphics -> REPRESENTATION -> item -> E-DRIFT-LINE" or "-> graphics -> REPRESENTATION -> item -> ION-DRIFT-LINE" if you are actually plotting drift-lines. [Default is "-> graphics -> REPRESENTATION -> item -> SOLID".] 2 PROJECT_MARKERS Projects one or more markers onto the viewing "-> &FIELD -> AREA -> plane" that has been chosen with the "-> &FIELD -> AREA" statement. The procedure should be only be called after a plot frame has been opened, e.g. with "-> Call -> PLOT_FIELD_AREA" or "-> Call -> PLOT_DRIFT_AREA". Format: !W
  CALL PROJECT_MARKERS("-> Call -> PROJECT_MARKERS -> vector"_1, vector_2, vector_3 [, "-> Call -> PROJECT_MARKERS -> representation"])
!W
3 vector The markers that have to be plotted should passed to the procedure as a set of 3 arguments which are either all of type "-> algebra -> variables -> types -> Number" or all of type "-> algebra -> variables -> types -> Matrix". If you use vectors as argument, then ensure that the vectors all have the same length, in the range [1,MXLIST]. 3 representation The polymarker representation that you wish to use for plotting the markers. Usually, this would be "-> graphics -> REPRESENTATION -> item -> FUNCTION-1", "-> graphics -> REPRESENTATION -> item -> FUNCTION-2" etc. [Default is "-> graphics -> REPRESENTATION -> item -> CROSS".] 2 RAINBOW Transforms a wave length into red-green-blue values. Format: !W
  CALL RAINBOW("-> Call -> RAINBOW -> wavelength", "-> Call -> RAINBOW -> red", "-> Call -> RAINBOW -> green", "-> Call -> RAINBOW -> blue")
!W
Example: !W
  // Wave length range
  Global wlmin = 350
  Global wlmax = 801
  // Start graphics
  Call "-> Call -> plot_start"
  Call "-> Call -> GKS_viewport"(1, 0.1, 0.9, 0.1, 0.9)
  Call "-> Call -> GKS_window"  (1, wlmin, wlmax, 0, 2)
  Call "-> Call -> GKS_select_nt"(1)
  // Axis, tickmarks and labels
  Call "-> Call -> plot_line"(wlmin, 1, wlmax, 1,`box-tickmarks`)
  For wl From wlmin To wlmax Step 50 Do
     Call "-> Call -> plot_line"(wl,1,wl,0.95,`box-tickmarks`)
     Call "-> Call -> plot_text"(wl,0.90,string(wl),`numbers`,`centre-top`)
  Enddo
  // Colours
  For wl From wlmin Step 1 To wlmax Do
     Call rainbow(wl,r,g,b)
     If r=0 & g=0 & b=0 Then Iterate
     !"-> graphics -> colour" rainbow red {r} green {g} blue {b}
     !"-> graphics -> representation" function-1 polyline-colour rainbow
     Call plot_line(wl,1.1,wl,2,`function-1`)
  Enddo
  // Close the plot
  Call "-> Call -> plot_end"
!W
3 wavelength Wavelength in nm, parametrised range: 380 nm to 780 m. Outside this range, a colour of (0,0,0) will be returned. This is an input argument which is not modified. 3 red Red fraction, on a scale of 0 to 1. See http://www.physics.sfasu.edu/astro/color.html for the expressions used. This argument must be modifiable, i.e. a simple global variable, not a constant or an expression. Any value associated with the variable before the call, will be lost. On return, the variable has type "-> algebra -> variables -> types -> Number". 3 green Green fraction, on a scale of 0 to 1. See http://www.physics.sfasu.edu/astro/color.html for the expressions used. This argument must be modifiable, i.e. a simple global variable, not a constant or an expression. Any value associated with the variable before the call, will be lost. On return, the variable has type "-> algebra -> variables -> types -> Number". 3 blue Blue fraction, on a scale of 0 to 1. See http://www.physics.sfasu.edu/astro/color.html for the expressions used. This argument must be modifiable, i.e. a simple global variable, not a constant or an expression. Any value associated with the variable before the call, will be lost. On return, the variable has type "-> algebra -> variables -> types -> Number". 2 REBIN_HISTOGRAM Groups bins of an histogram. This procedure does not change the range of the histogram. To reduce the range, use "-> Call -> CUT_HISTOGRAM". This procedure may be called while filling is in progress, but should not be called for "-> Call -> BOOK_HISTOGRAM -> options -> AUTOSCALE" histograms before the range has been established. If the calculation fails (invalid arguments etc), then the global variable "-> algebra -> variables -> predefined -> OK" will be set to False, otherwise to True. Format: !W
  CALL REBIN_HISTOGRAM("-> Call -> REBIN_HISTOGRAM -> ref_in", "-> Call -> REBIN_HISTOGRAM -> ngroup", "-> Call -> REBIN_HISTOGRAM -> ref_out")
!W
Example: !W
  Call "-> Call -> book_histogram"(gauss,200,-10,10)
  For i From 1 To 500 Do
     Call "-> Call -> fill_histogram"(gauss,"-> algebra -> functions -> rnd_gauss")
  Enddo
  Call "-> Call -> plot_histogram"(gauss)
  Call "-> Call -> plot_end"

  Call rebin_histogram(gauss,5,new)
  Call hplot(new)
  Call "-> Call -> plot_end"
!W
An histogram is filled with fine binning, and then rebinned for better readability. 3 ref_in Should contain on entry an "-> algebra -> variables -> types -> Histogram" of which you wish to group the bins. This histogram is not modified by the procedure. [No default, this is a mandatory argument.] 3 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 "-> algebra -> variables -> types -> 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.] 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. It is permissible that ref_out and "-> Call -> REBIN_HISTOGRAM -> ref_in" coincide. 2 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 "-> Call -> BOOK_HISTOGRAM -> options -> 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 "-> Call -> BOOK_HISTOGRAM". If arguments are omitted altogether, then all histograms currently stored as global variables are reset. Format: !W
  CALL RESET_HISTOGRAM(hist1, hist2, ...)
!W
2 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 "-> Call -> 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. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the matrix is successfully reshaped, and to False in case of a problem. Format: !W
  CALL RESHAPE_MATRIX("-> Call -> RESHAPE_MATRIX -> matrix", "-> Call -> RESHAPE_MATRIX -> size"_1, size_2, ..., size_n, "-> Call -> RESHAPE_MATRIX -> pad")
!W
Example: !W
  (assume that B is a 3\×4 matrix)
  Global a=b[2;]
  Call reshape_matrix(b,4,0.0)
!W
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. 3 matrix The "-> algebra -> variables -> types -> 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.] 3 size A set of "-> algebra -> variables -> types -> Number"s, 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.] 3 pad A "-> algebra -> variables -> types -> 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.] 2 RND_MULTIPLICATION Performs a Monte Carlo simulation of the number of electrons created and absorbed along the current electron drift-line. Unlike "-> Call -> 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 "-> &DRIFT -> methods -> Runge_Kutta_Fehlberg" and with "-> &DRIFT -> methods -> Monte_Carlo" methods. In the latter case, the use of the "-> &DRIFT -> INTEGRATION-PARAMETERS -> 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: !W
  CALL RND_MULTIPLICATION(ne, [ni])
!W
Example: !W
  "-> &DRIFT"
  "-> &DRIFT -> integration-parameters" projected m-c-dist-int 0.0002
  Call "-> 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 "-> Call -> book_histogram"(hist,50,0,2*aval*att)
  "-> Global" nrndm=500
  For i From 1 To nrndm Do
     Call "-> Call -> drift_mc_electron"(0.15,0,0)
     Call rnd_multiplication(a)
     Call "-> Call -> fill_histogram"(hist,a)
     If "-> algebra -> functions -> entier"(i/100)*100=i Then
        !"-> graphics -> options" log-y
        Call "-> Call -> plot_histogram"(hist)
        Call "-> Call -> plot_end"
     Endif
  Enddo
!W
2 RND_IONISATION_ENERGY Generates a random energy to create one electron in a gas such that a high energies the given asymptotic work function and Fano factor are reached. This distribution, empirical in nature and introduced by I.B. Smirnov [NIM A 554 (2005) 474-493] is used by the Heed program to convert electromagnetic energy loss into electron-ion pairs. It is generated from a standardised distribution with parameters w=30 eV and F=0.174 which is zero below w/2, flat from w/2 to w, falling with the 4th power of the energy until 3.064 w and zero beyond. It is scaled to the desired work function and Fano factor settings. As a result of this scaling, especially when F>0.174, values below w/2 can occur. !W
!W !W
Format: !W
  CALL RND_IONISATION_ENERGY(work_function, fano_factor, random_energy)
!W
Example: Verification that the generator indeed asymptotically produces the specified work function and Fano factor. !W
  "-> Global" emin=10
  "-> Global" emax=500
  "-> Global" npoint=50
  Call "-> Call -> book_matrix"(evec,npoint)
  Call "-> Call -> book_matrix"(rmsvec,npoint)
  Call "-> Call -> book_matrix"(meanvec,npoint)
  Call "-> Call -> book_histogram"(nhist,100,-0.5,99.5)

  Global w=20
  Global f=0.2

  For ie From 1 To npoint "-> Do"
     Call "-> Call -> book_histogram"(nhist,100,-0.5,99.5)
     "-> Global" estart=emin*(emax/emin)^((ie-1)/(npoint-1))
     For irndm From 1 To 100000 Do
        "-> Global" ne=0
        "-> Global" etot=estart
        Do
           Call rnd_ionisation_energy(w,f,eloss)
           If etot-eloss>0 Then
              "-> Global" etot=etot-eloss
              "-> Global" ne=ne+1
           Else
              "-> Do -> Leave"
           Endif
        Enddo
        Call "-> Call -> fill_histogram"(nhist,ne)
     Enddo
     "-> Global" evec[ie]=estart
     "-> Global" rmsvec[ie]="-> algebra -> functions -> rms"(nhist)
     "-> Global" meanvec[ie]="-> algebra -> functions -> mean"(nhist)
  Enddo

  !"-> graphics -> options" log-x
  Call "-> Call -> plot_frame"(emin,0,emax,80,`Energy [eV]`, ...
     `Energy deposited per electron [eV]`, ...
     `Energy used per electron`)
  Call "-> Call -> plot_line"(evec,evec/meanvec,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  "-> Global" v=70
  Call "-> Call -> plot_line"(50,v,80,v,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_text"(100,v,`Heed model`,`"-> graphics -> REPRESENTATION -> item -> function-1"`,`left-half`)
 
  Global fvec=w/(1-0.45*w/evec)
  Call "-> Call -> plot_line"(evec[2+"-> algebra -> functions -> row"("-> algebra -> functions -> size"(evec)-2)],fvec[2+"-> algebra -> functions -> row"("-> algebra -> functions -> size"(evec)-2)], ...
     `"-> graphics -> REPRESENTATION -> item -> function-2"`)
  "-> Global" v=v-5
  Call "-> Call -> plot_line"(50,v,80,v,`"-> graphics -> REPRESENTATION -> item -> function-2"`)
  Call "-> Call -> plot_text"(100,v,`W/(1-V/E)`,`"-> graphics -> REPRESENTATION -> item -> function-2"`,`left-half`)
  Call "-> Call -> plot_line"(emin,w,emax,w,`"-> graphics -> REPRESENTATION -> item -> comment"`)
  Call "-> Call -> plot_text"(15,22,`ws`,`"-> graphics -> REPRESENTATION -> item -> title"`)
  Call "-> Call -> plot_end"
 
  Call "-> Call -> plot_frame"(emin,0,emax,0.5,`Energy [eV]`, ...
     `RMS2/mean`,`Fano factor`)
  Call "-> Call -> plot_line"(evec,rmsvec^2/meanvec,`"-> graphics -> REPRESENTATION -> item -> function-1"`)
  Call "-> Call -> plot_line"(emin,f,emax,f,`"-> graphics -> REPRESENTATION -> item -> comment"`)
  Call "-> Call -> plot_text"(50,0.16,`Asymptotic Fano factor`,`"-> graphics -> REPRESENTATION -> item -> title"`)
  !rep "-> graphics -> REPRESENTATION -> item -> comment" linetype solid
  Call "-> Call -> plot_arrow"(w,0.03,w,0,`"-> graphics -> REPRESENTATION -> item -> comment"`)
  !rep "-> graphics -> REPRESENTATION -> item -> comment" linetype dashed
  Call "-> Call -> plot_text"(w,0.042,`Mean work`,`"-> graphics -> REPRESENTATION -> item -> title"`,`centre,half`)
  Call "-> Call -> plot_end"
!W
2 RND_VAVILOV Generates Vavilov distributed random numbers. This procedure relies on the G116 procedures of the CERN program library, a high-precision evaluation of the Vavilov distribution, typically 5 decimal are correct. Random numbers are generated using the V152 procedures. See the writeups http://consult.cern.ch/shortwrups/g116/top.html and http://consult.cern.ch/shortwrups/v152/top.html for particulars. The following restrictions apply: 0.01\ \≤\ \κ\ \≤\ 10 and 0\ \≤\ \β\²\ \≤\ 1 The procedure seems to have difficulty coping with a few narrow ranges of \κ values (around 0.35 and 0.92), for broad ranges of \β\². In those cases, a value of 0 is returned. A faster, but considerably less accurate, version is available with the "-> Call -> RND_VAVILOV_FAST" procedure. Format: !W
  CALL RND_VAVILOV(\κ, \β\², random_number)
!W
2 RND_VAVILOV_FAST Generates Vavilov distributed random numbers. This procedure relies on the G115 procedures in the CERN program library. This is a low-precision evaluation of the Vavilov distribution, typically only 1-2 decimal places are correct. See the writeup for particulars: http://consult.cern.ch/shortwrups/g115/top.html for particulars. The following restrictions apply: 0.01\ \≤\ \κ\ \≤\ 12 and 0\ \≤\ \β\²\ \≤\ 1 A much slower, but considerably more accurate, version is available with the "-> Call -> RND_VAVILOV" procedure. Format: !W
  CALL RND_VAVILOV(\κ, \β\², random_number)
!W
2 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 "-> Call -> GKS_AREA", most other procedures set the attributes before plotting. Format: !W
  CALL SET_AREA_ATTRIBUTES("-> Call -> SET_AREA_ATTRIBUTES -> representation")
!W
3 representation One of the existing fill area representations. This argument is a text string. [No default, this is a mandatory parameter.] 2 SET_LINE_ATTRIBUTES Selects a given representation for the next polyline. Calling this procedure is useful only if you draw the next polyline with "-> Call -> GKS_POLYLINE", most other procedures set the attributes before plotting. Format: !W
  CALL SET_LINE_ATTRIBUTES("-> Call -> SET_LINE_ATTRIBUTES -> representation")
!W
3 representation One of the existing polyline representations. This argument is a text string. [No default, this is a mandatory parameter.] 2 SET_MARKER_ATTRIBUTES Selects a given representation for the next polymarker. Calling this procedure is useful only if you draw the next polymarker with "-> Call -> GKS_POLYMARKER", most other procedures set the attributes before plotting. Format: !W
  CALL SET_MARKER_ATTRIBUTES("-> Call -> SET_MARKER_ATTRIBUTES -> representation")
!W
3 representation One of the existing polymarker representations. This argument is a text string. [No default, this is a mandatory parameter.] 2 SET_TEXT_ATTRIBUTES Selects a given representation for the next text. Calling this procedure is useful only if you draw the next text with "-> Call -> GKS_TEXT", most other procedures set the attributes before plotting. Format: !W
  CALL SET_TEXT_ATTRIBUTES("-> Call -> SET_TEXT_ATTRIBUTES -> representation")
!W
3 representation One of the existing text representations. This argument is a text string. [No default, this is a mandatory parameter.] 2 SKIP_HISTOGRAM When histograms are overlaid, their "-> Call -> PLOT_HISTOGRAM -> representations" are taken from a fixed sequence. Using the SKIP_HISTOGRAM procedure, you can skip one (default) or more histograms from this sequence. Format: !W
  CALL SKIP_HISTOGRAM([number_to_be_skipped])
!W
Example: Suppose, we usually plot 3 histograms in a row and now wish to comment one of these out, without changing the representations of the others. Then we could do this: !W
  Call plot_histogram(hnheed,`ne`,`Electron count`)
  * Call plot_histogram(hnexp,``,``,`noframe`)
  Call skip_histogram
  Call plot_histogram(hnsrim,``,``,`noframe`)
  Call plot_end
!W
2 SOLVE_EQUATION (Not yet available) 2 SORT_MATRIX Takes a "-> algebra -> variables -> types -> Matrix" as argument and sorts its elements in increasing numerical order. Sorting a matrix of higher dimensionality than 1 is equivalent to first unravelling the matrix, sorting its elements and then restoring the original shape of the matrix. Format: !W
  CALL SORT_MATRIX(matrix)
!W
2 SLEEP Pauses program execution for a number of seconds. This procedure is available only in Lunix compilations. Format: !W
  CALL SLEEP(seconds)
!W
2 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: !W
  CALL STORE_SIGNAL("-> Call -> STORE_SIGNAL -> electrode", "-> Call -> STORE_SIGNAL -> direct" [, "-> Call -> STORE_SIGNAL -> cross-induced"])
!W
3 electrode This is a "-> algebra -> variables -> types -> Number" which identifies 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed and will display the numbers by which they are identified. [No default, this is a mandatory parameter.] 3 direct Should contain a "-> algebra -> variables -> types -> Matrix" of the same overall size as the number of signal sampling points set with the "-> &SIGNAL -> WINDOW" command. The matrix does not have to be 1-dimensional. The matrix should contain the signal directly induced into the electrode specified with the first argument, at time intervals established with the WINDOW command. [This is a mandatory argument.] 3 cross-induced Should contain a "-> algebra -> variables -> types -> Matrix" of the same overall size as the number of signal sampling points set with the "-> &SIGNAL -> WINDOW" command. The matrix does not have to be 1-dimensional. The matrix should contain the cross induced signal of the electrode specified with the first argument, at time intervals established with the WINDOW command. [This is a mandatory argument.] 2 STORE_SUBMATRIX Stores a "-> algebra -> variables -> types -> 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: !W
  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)
!W
2 STRING_DELETE Returns the string with the part between characters istart and iend (both inclusive) deleted. Format: !W
  CALL STRING_DELETE("-> Call -> STRING_DELETE -> string", "-> Call -> STRING_DELETE -> istart", "-> Call -> STRING_DELETE -> iend", "-> Call -> STRING_DELETE -> output")
!W
Example: !W
  Call string_delete(`abc def ghi`,4,8,out)
!W
3 string A variable or an expression that evaluates to a "-> algebra -> variables -> types -> String". A mandatory argument, not modified by the procedure. 3 istart A "-> algebra -> variables -> types -> Number" that indicates the first character to be deleted. A mandatory argument, not modified by the procedure. 3 iend A "-> algebra -> variables -> types -> Number" that indicates the last character to be deleted. A mandatory argument, not modified by the procedure. 3 output Contains on successful completion the "-> algebra -> variables -> types -> String" that results from the removal of the specified characters from the input string. Should be a modifiable argument. Any data contained in this argument before the procedure is called, is lost after the procedure call. 2 STRING_INDEX Returns the starting position of a substring in a "-> algebra -> variables -> types -> String". The first character of a string is numbered 1. Returns 0 if the substring is not found within the string. Format: !W
  CALL STRING_INDEX(string, substring, index)
!W
Example: !W
  Call string_index(`abc def`,`def`,pos)
  Say "`def` starts at character {pos} in `abc def`"
!W
2 STRING_LENGTH Returns the number of characters in a "-> algebra -> variables -> types -> String". Format: !W
  CALL STRING_LENGTH(string, length)
!W
Example: !W
  Call string_length(`abc`,n)
  Say "Length of string is {n} characters."
!W
2 STRING_LOWER Converts a "-> algebra -> variables -> types -> String" to lower case. Format: !W
  CALL STRING_LOWER(string)
!W
Example: !W
  Global str=`ABCDEF`
  Call string_lower(str)
  Say {str}
!W
2 STRING_MATCH Tells whether a "-> algebra -> variables -> types -> 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: !W
  CALL STRING_MATCH(string, pattern, match)
!W
Example: !W
  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
!W
2 STRING_PORTION Returns the part of the "-> algebra -> variables -> types -> 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: !W
  CALL STRING_PORTION(string, istart, iend, portion)
!W
Example: !W
  Call string_portion(`abc def ghi`,5,7,out)
  Say "Characters 5 through 7 of `abc def ghi` are: {out}"
!W
2 STRING_REPLACE Replaces all occurrences of "search" (2nd argument) by "replace" (3rd argument) in the "-> algebra -> variables -> types -> String" "string". This procedure does not replace characters that stem from earlier replacements. Format: !W
  CALL STRING_REPLACE(string, search, replace)
!W
Examples: !W
  Global mixture=`argon 90 methane 10`
  Global gas_file=mixture/`.gas`
  Call string_replace(gas_file,` `,`_`)
  Say "|{gas_file}|"
!W
In order to create a file name without blanks from a gas mixture, the blanks are replaced by underscores. !W
  Vector a
  1.23 2.34 3.45 4.56

  Global b="-> algebra -> functions -> string"(a)
  Call string_replace(b,`, `,` `)
  Call string_replace(b,`(`,``)
  Call string_replace(b,`)`,``)
  Say "-{b}-"
!W
Prints the vector A without parentheses and commata. !W
  Global a=`baaaaa`
  Call string_replace(a,`ba`,`bbb`)
  Say "|{a}|"
!W
After the call, a will be equal to `bbbaaaa` and not `bbbbbbbbbbb`. 2 STRING_UPPER Converts a "-> algebra -> variables -> types -> String" to upper case. Format: !W
  CALL STRING_UPPER(string)
!W
Example: !W
  Global str=`abcdef`
  Call string_upper(str)
  Say {str}
!W
2 STRING_WORD Returns the i'th blank, comma or equal sign delimited word from a "-> algebra -> variables -> types -> String". Format: !W
  CALL STRING_WORD(string, i, word)
!W
Example: !W
  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
!W
2 STRING_WORDS Returns the number of words in a "-> algebra -> variables -> types -> String". Words are delimited by blanks, commata, colons and equal signs. Format: !W
  CALL STRING_WORDS(string, n)
!W
Example: !W
  See "-> Call -> STRING_WORD"
!W
2 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: !W
  CALL TIME_LOGGING( string )
!W
Example: !W
  Call time_logging(`Until timing test`)
  "-> Global" x0=0.5
  Global y0=1.5
  Call "-> Call -> plot_drift_area"
  For i From 1 To 100 Do
     Call "-> Call -> drift_mc_electron"(x0, y0, 0, status, time)
     Call "-> Call -> plot_drift_line"
  Enddo
  Call time_logging(`MC drifting`)
!W
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. 2 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: !W
  CALL THRESHOLD_CROSSING("-> Call -> THRESHOLD_CROSSING -> electrode", "-> Call -> THRESHOLD_CROSSING -> threshold", "-> Call -> THRESHOLD_CROSSING -> options", ...
     "-> Call -> THRESHOLD_CROSSING -> ntime", "-> Call -> THRESHOLD_CROSSING -> time"1 [,time2 [,time3 ...]])
!W
Example: !W
  For i From 1 To 100 Do
     "-> &SIGNAL -> signal"
     "-> &SIGNAL -> convolute-signals" range 0 1000 ...
        transfer-function (5*t/0.01)^5*"-> algebra -> functions -> 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
!W
3 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 "-> &SIGNAL -> SELECT" command. SELECT without arguments will show how the groups are composed. [No default, this is a mandatory parameter.] 3 threshold The threshold level, if the signal has not been processed, it is in \μA. 3 options This argument is a character string composed of the following words, separated by blanks, comma's etc. Case is irrelevant. !Wtable_start !T+P + . -------------------------------------------------------------------- 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 -------------------------------------------------------------------- !Wtable_end Notes: !Wol_start 1. Several synonyms of the above are accepted too. 2. This procedure detects either rising or falling edges, but not both at the same time. !Wol_end 3 ntime Contains, on successful completion, the total "-> algebra -> variables -> types -> Number" of threshold crossings found, including those which are not returned for lack of arguments supplied. [This is a mandatory argument which must be modifiable.] 3 time Each of these arguments contains on successful completion one of the threshold crossings that have been found. These arguments will be of type "-> algebra -> variables -> types -> Number" If there are more return arguments than threshold crossings, then the excess arguments are set to Nill, which is of type "-> algebra -> variables -> types -> Undefined". If more threshold crossings are found than return arguments are provided, then the excess crossing are not returned. The threshold crossings are returned in increasing order, [One such argument is mandatory, all these arguments must be modifiable.] 2 TOWNSEND Returns the Townsend coefficient, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. If the magnetic field is omitted, then all 3\ components are assumed to be zero, irrespective of the magnetic field settings that may be in effect. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The Townsend coefficient is returned in 1/cm. Formats: !W
  CALL TOWNSEND(e, townsend)
  CALL TOWNSEND(ex, ey, ez, townsend)
  CALL TOWNSEND(ex, ey, ez, bx, by, bz, townsend)
!W
2 TRANSVERSE_DIFFUSION Returns the transverse diffusion, if available, for a given electric field, a given electric field vector or a given combination of an electric and a magnetic field vector. In the absence of a magnetic field, the orientation of the electric field is immaterial. The electric field may be specified either by the norm or as a vector, of which only the norm matters. In the presence of a magnetic field, the transport parameters depend on the relative orientation of the electric and magnetic field vectors. Both fields therefore have to be specified as vectors. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify 1 or 2 components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm. The magnetic field, if present, should be expressed in native units of 0.01\ T or 100\ G. The diffusion is returned in \√cm. SIGMA_T can be used as a synonym for TRANSVERSE_DIFFUSION. Formats: !W
  CALL TRANSVERSE_DIFFUSION(e, sigma_t)
  CALL TRANSVERSE_DIFFUSION(ex, ey, ez, sigma_t)
  CALL TRANSVERSE_DIFFUSION(ex, ey, ez, bx, by, bz, sigma_t)
!W
2 VAVILOV Returns a Vavilov probability. This procedure accepts both a "-> algebra -> variables -> types -> Number" and a "-> algebra -> variables -> types -> Matrix" as 3rd argument. The value that is returned will be of the same type and shape. This procedure relies on the G116 procedures in the CERN program library. This is a higher-precision evaluation of the Vavilov distribution than the one used for "-> Call -> RND_VAVILOV", and is typically correct to 5 decimal places. See the writeup for particulars: http://consult.cern.ch/shortwrups/g116/top.html for particulars. The following restrictions apply: 0.01\ \≤\ \κ\ \≤\ 10 and 0\ \≤\ \β\²\ \≤\ 1 Format: !W
  CALL VAVILOV(\κ, \β\², \λ, probability)
!W
2 VELOCITY_BTRANSVERSE Returns the component of drift velocity in the direction perpendicular to E and to E\×B, if such data is available, for given E and B fields. This component is zero when there is no magnetic field. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the drift velocity is returned in cm/\μsec. Format: !W
  CALL VELOCITY_BTRANSVERSE(ex, ey, ez, bx, by, bz, drift)
!W
2 VELOCITY_E Returns the component of drift velocity parallel with E, if such data is available, for given E and B fields. If there is no magnetic field, then the magnetic field must not be specified. In this case, the values returned by this procedure coincide with those returned by "-> Call -> DRIFT_VELOCITY". Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the drift velocity is returned in cm/\μsec. Format: !W
  CALL VELOCITY_E(ex, ey, ez, bx, by, bz, drift)
!W
Example: !W
  "-> &GAS"
  "-> &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)^(("-> algebra -> functions -> row"(n)-1)/(n-1))
  Call velocity_e(0,0,e,v)
  !"-> graphics -> options" log-x
  Call "-> Call -> plot_graph"(e,v,`E [V/cm]`,`Drift velocity [cm/microsec]`, ...
     `Magboltz vs Zhao et al.`)
  "-> 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

  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 "-> Call -> plot_error_bar"(ezhao*1000,vzhao,`circle`)
  Call "-> Call -> plot_end"
!W
Magboltz is used to compute the drift velocity in a mixture of 92\ % argon and 8\ % CO\2\. 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://cern.ch/garfield/examples/gas/ArCO2_detail.html 2 VELOCITY_ExB Returns the component of drift velocity in the E\×B direction, if such data is available, for given E and B fields. This component is zero when there is no magnetic field. Each of the field components can either be a "-> algebra -> variables -> types -> Number" or a "-> algebra -> variables -> types -> Matrix". It is permissible to specify some components of the field as Numbers and the other(s) as Matrices. All components which are specified as Matrix, must have the same total size - they do not have to be 1-dimensional. If at least one component is specified as Matrix, then the output will be a 1-dimensional Matrix with length equal to the overall size of the arguments of type Matrix. Otherwise the result will be a Number. The electric field should be in V/cm, the magnetic field has to be in native units of 100\ G or 0.01\ T, and the drift velocity is returned in cm/\μsec. Format: !W
  CALL VELOCITY_ExB(ex, ey, ez, bx, by, bz, drift)
!W
2 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 "-> Call -> 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: !W
  CALL WEIGHTING_FIELD(x, y, ex, ey, ez, "-> Call -> WEIGHTING_FIELD -> electrode")
!W
3 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: assumed to be 0
!W
The transformation from (x,y) to (\ρ,\φ) can be performed by the "-> Call -> CARTESIAN_TO_INTERNAL" procedure. 3 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: !W
  Er   = Ex/r
  Ephi = Ey/r
  Ez   = Ez
!W
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 "-> &FIELD -> SELECT" without arguments. [This argument is compulsory.] 2 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 "-> Call -> WEIGHTING_FIELD" in that it expects an (x,y,z) set of coordinates. This procedure should be called from within the signal section. Format: !W
  CALL WEIGHTING_FIELD_3(x, y, z, ex, ey, ez, "-> Call -> WEIGHTING_FIELD_3 -> electrode")
!W
3 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: !W
  for x: log(r)
  for y: \φ, in radians
  for z: z
!W
The transformation from (x,y) to (\ρ,\φ) can be performed by the "-> Call -> CARTESIAN_TO_INTERNAL" procedure. 3 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: !W
  Er   = Ex/r
  Ephi = Ey/r
  Ez   = Ez
!W
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 "-> &FIELD -> SELECT" without arguments. This argument is mandatory. 2 WRITE_HISTOGRAM Writes an histogram to disk in such a format that it can be read back by Garfield with the "-> Call -> GET_HISTOGRAM" procedure. Histograms can, by means of the "-> Call -> WRITE_HISTOGRAM_RZ" procedure, also be written out in a format suitable for use with PAW. Using the h2root program, such files can be converted for use with root, see http://root.cern.ch/root/HowtoConvert.html Calling this procedure does not interfere with filling of the histogram and an autorange histogram can be written to disk before the range has been set. This procedure is for instance used when one job fills a set of histograms which are, probably repeatedly, fitted by another job. Another application is a found in calculations where statistics are accumulated over a series of jobs. The first job would create the histogram and fill it, all successive jobs read the existing histogram, continue filling it, and write it back to the file at the end of the job. Care should be taken that the global option "-> OPTIONS -> DELETE-OLD-MEMBER" has been switched on before doing this. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the histogram has been written and to False if it hasn't. Format: !W
  CALL WRITE_HISTOGRAM("-> Call -> WRITE_HISTOGRAM -> reference", "-> Call -> WRITE_HISTOGRAM -> file" [, "-> Call -> WRITE_HISTOGRAM -> member" [, "-> Call -> WRITE_HISTOGRAM -> remark"]])
!W
Example: !W
  "-> Global" chamber=1

  (calculation of e.g. arrival time histograms for chamber 1)

  Global hfile `CHAMBER`/"-> algebra -> functions -> string"(chamber)/`.HIST`
  Global i=0                                                 
  Global exist=True   
  Global n=0                                    
  While exist "-> Do"
     Global i=i+1
     Call "-> 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."
!W
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. 3 reference The "-> algebra -> variables -> types -> Histogram" is referenced via a global variable or an expression in terms of global variables. Histogram references can be created with calls to "-> Call -> BOOK_HISTOGRAM" or "-> Call -> GET_HISTOGRAM". Histogram references are also created by arithmetic between existing histograms. If this argument is an expression which results in an histogram, the member name should be specified. 3 file The name of the Garfield "-> dataset -> structure -> file" to which the histogram should be written. This argument should be of type "-> algebra -> variables -> types -> String". 3 member The name to be given to the "-> dataset -> structure -> 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. This argument should be of type "-> algebra -> variables -> types -> String". 3 remark A "-> dataset -> structure -> remark" string that helps in identifying the member. [By default, set to "none".] 2 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 process the data with your own program, then it is probably advisable to write the histogram in Garfield format using the "-> Call -> WRITE_HISTOGRAM" procedure. RZ files can be converted for use by root with the h2root program, see http://root.cern.ch/root/HowtoConvert.html An autorange histogram can only be written out to an RZ file once its range has been established. Use the "-> Call -> WRITE_HISTOGRAM" and "-> Call -> GET_HISTOGRAM" procedures to save and recover such an histogram. The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the histogram has been written and to False if it hasn't. Format: !W
  CALL WRITE_HISTOGRAM_RZ(["-> Call -> WRITE_HISTOGRAM_RZ -> reference" [, "-> Call -> WRITE_HISTOGRAM_RZ -> file" [, "-> Call -> WRITE_HISTOGRAM_RZ -> title"]]])
!W
Example: !W
  Call "-> Call -> book_histogram"(a,200)
  For i From 1 To 10000 Do
     Call "-> Call -> fill_histogram"(a,rnd_landau)
  Enddo
  Call "-> Call -> plot_histogram"(a,`Energy`,`Landau`)
  Call "-> Call -> plot_end"
  Call write_histogram_rz(a,`hist.rz`,`Landau distribution`)
!W
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: !W
  h/file 20 hist.rz
  h/pl 1
!W
3 reference The "-> algebra -> variables -> types -> Histogram" is referenced via a global variable or an expression in terms of global variables. Histogram references can be created with calls to "-> Call -> BOOK_HISTOGRAM" or "-> Call -> 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.] 3 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: !W
  h/pl 5
!W
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: !W
  h/pl 5;3
!W
3 file A "-> algebra -> variables -> types -> String" which contains 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`.] 3 title A "-> algebra -> variables -> types -> String" with 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.] 2 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 "-> Call -> 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://cern.ch/garfield/examples/load_garf.m The procedure sets the "-> algebra -> variables -> predefined -> OK" global variable to True if the matrix is successfully written, and to False in case of a problem. Format: !W
  CALL WRITE_MATRIX("-> Call -> WRITE_MATRIX -> matrix", "-> Call -> WRITE_MATRIX -> file" [, "-> Call -> WRITE_MATRIX -> member"])
!W
Example: !W
  If "-> algebra -> functions -> type"("-> algebra -> functions -> global"(`ABC`))#`Matrix` Then
     Call "-> Call -> inquire_member"(`abc.mat`,`abc`,`matrix`,exist)
     If exist Then
        Call "-> Call -> get_matrix"(abc,`abc.mat`)
        Call "-> Call -> dimensions"(abc,n_dim,dim_abc)
        Global nx="-> algebra -> functions -> number"(dim_abc[1])
        Global ny="-> algebra -> functions -> number"(dim_abc[2])
        Call "-> Call -> delete_matrix"(dim_abc)
     Else
        Global nx=20
        Global ny=30
        Call "-> Call -> book_matrix"(abc,nx,ny)
        For i From 1 To nx Do
           For j From 1 To ny Do
              Global abc[i;j]="-> algebra -> functions -> sin"(i)*"-> algebra -> functions -> exp"(j/10)
           Enddo
        Enddo
        Call write_matrix(abc,`abc.mat`)
     Endif
  Endif
!W
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. 3 matrix This argument can be either a global variable associated with a "-> algebra -> variables -> types -> Matrix", or an expression in terms of global variables that results in a matrix. A matrix reference is usually created with a call to "-> Call -> BOOK_MATRIX", using the "-> algebra -> functions -> ROW" function or by arithmetic between existing matrices. If this argument is an expression which results in a matrix, then the member name should be specified. 3 file The name of the Garfield "-> dataset -> structure -> file" to which the matrix is to be written. This argument should be of type "-> algebra -> variables -> types -> String". 3 member The name to be given to the "-> dataset -> structure -> member" in 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. This argument should be of type "-> algebra -> variables -> types -> String". 2 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. Do not confuse this procedure with the "-> algebra -> functions -> ZEROES" function. Format: !W
  CALL ZEROES(x_"-> Call -> ZEROES -> vector", y_vector, "-> Call -> ZEROES -> nzero", "-> Call -> ZEROES -> zero"1, zero2, ...)
!W
Examples: !W
  Call "-> Call -> get_signal"(1,time,direct,cross)
  "-> Global" signal=direct+cross
  Call zeroes(time,signal/maximum(signal)-0.5,nz,t1,t2)
  If nz<2 Then
     Say "Time range not long enough to determine FWHM."
  Else
     Say "FWHM of the signal: {t2-t1}"
  Endif

  Global r="-> algebra -> functions -> row"(200)/10
  Global v="-> algebra -> functions -> sin"(r)
  Call zeroes(r,v,nz,z1,z2,z3)
  Say "Zeroes: {nz} - {z1,z2,z3}"
!W
The first example computes the FWHM of a signal, the second example finds the zeroes of the sine function. 3 vector The arguments x_vector and y_vector should both be of type "-> algebra -> variables -> types -> 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 unravelled. [These arguments are mandatory. No default is supplied.] 3 nzero Is set on return to the "-> algebra -> variables -> types -> Number" of zeroes that have been found. 3 zero 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 set to Nill, which is of type "-> algebra -> variables -> types -> Undefined". If more zeroes are found than return arguments are provided, then the excess zeroes are not returned. The zeroes are returned in numerically increasing order, irrespective of the order of the ordinate vector. 1 Do !W
Do not use curly brackets in Do statements. !W
Do loops are used to repeatedly execute a set of lines. There are 3 types of loops in Garfield: !Wul_start - Loops usually have a variable associated to them that is incremented or decremented at each iteration. This variable will run through the range you indicate until the While condition fails or the Until condition holds. We call this type the "From-Step-To" loop. - Alternatively, the variable can assume in sequence the value of all elements of a matrix. You can combine this with While and Until conditions. This we call an "In" loop. - Garfield also allows so-called "Leave" loops which have no such variable. These loops can only be left using the Leave statement. !Wul_end Do not attempt to "-> input" a file with < while in a Do loop. Format of a "From-Step-To" loop: !W
  For "-> Do -> var" From "-> Do -> from" [Step "-> Do -> step"] To "-> Do -> to" [While "-> Do -> while"] [Until "-> Do -> until"] Do
     [statement | "-> Do -> Leave" [var] | "-> Do -> Iterate" [var]]
     ...
  Enddo
!W
Example: !W
  For i From 1 To 5 Do
     Say "Now I has the value {I}."
  Enddo
  Say "Finished !"
!W
Format of an "In" loop: !W
  For "-> Do -> var" In "-> Do -> in" [While "-> Do -> while"] [Until "-> Do -> until"] Do
     [statement | "-> Do -> Leave" [var] | "-> Do -> Iterate" [var]]
     ...
  Enddo
!W
Example: !W
  Vector angles
  0 1 2 5 10 30 60 90

  For angle In angles Do
     &SIGNAL
     (various signal settings required here)
     track 0.2 2 0.2 {2+0.4*tan(pi*angle/180)} pion energy 5 GeV
     signal
  Enddo
!W
Signals are computed for tracks at various inclinations. Format for a "Leave" loop: !W
  [While "-> Do -> while"] [Until "-> Do -> until"] Do
     [statement | "-> Do -> Leave" [var] | "-> Do -> Iterate" [var]]
     ...
  Enddo
!W
Example: !W
  Do
     Say "Please enter a number"
     "-> Parse" Terminal x
     If "-> algebra -> functions -> type"(x)=`Number` Then Leave
     Say "{x} is not a number, try again"
  Enddo
  Say "You entered {x}"
!W
This fragment will keep asking for a value to be given to x until what the user types can be identified as being numeric. 2 var When you use the For clause followed by the name of a variable, you request this variable to be incremented before each iteration of the loop. You must in this case specify either !Wul_start - an initial "-> Do -> from" value and a final "-> Do -> to" value, optionally also a "-> Do -> step" size; or - a matrix "-> Do -> in" which the values for the variable are stored. !Wul_end You may change the value of this variable inside the loop. If you do so in a "From-Step-To" loop, then the increment for the next iteration will be added to the modified value. Such a modification has no effect on the next iteration in a "In" loop, nor does it affect the contents of the matrix from which the values are taken. The loop variable can be used anywhere inside the body of the loop to perform calculations. It can also be referenced in the "-> Do -> Leave" and "-> Do -> Iterate" statements. The loop variable is a "-> Global" of type "-> algebra -> variables -> types -> Number". It does not have to be declared before the loop. Its name should obey the "-> algebra -> variables -> naming" conventions for global variables. [This is an optional parameter.] 2 from The initial value of the loop variable. This parameter must be a "-> Global" variable of type "-> algebra -> variables -> types -> Number" or an expression that evaluates to a Number. "From-Step-Do" loops should not have an In clause. [This argument is mandatory for "From-Step-To" loops. No default is provided.] 2 step The increment of the loop variable. The increment may assume positive and negative values. Also 0 is permitted. This parameter must be a "-> Global" variable of type "-> algebra -> variables -> types -> Number" or an expression that evaluates to a Number. This expression is evaluated anew at each iteration. "From-Step-Do" loops should not have an In clause. [This argument is permitted only in "From-Step-To" loops. If no step size is indicated, a default value of 1 is assumed.] 2 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 parameter must be a "-> Global" variable of type "-> algebra -> variables -> types -> Number" or an expression that evaluates to a Number. This expression is evaluated anew each iteration. "From-Step-Do" loops should not have an In clause. [This argument is mandatory for "From-Step-To" loops. No default is provided.] 2 in Should be an expression that evaluates to a "-> algebra -> variables -> types -> Matrix". This matrix is allowed to have any number of dimensions. The loop variable will assume each of the values found in the matrix, unless the loop is terminated via While, Until or Leave. This expression is evaluated anew at each iteration. It is permissible to modify the matrix in the body of the loop. From, Step and To must not be used in "In" loops, but you may use While and Until. [This argument is mandatory for "In" loops. There is no default matrix.] 2 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 parameter must be a "-> Global" variable of type "-> algebra -> variables -> types -> Logical" or an expression that evaluates to a Logical. This expression is evaluated anew each iteration. [This optional parameter is by default set to True.] 2 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. This parameter must be a "-> Global" variable of type "-> algebra -> variables -> types -> Logical" or an expression that evaluates to a Logical. [This optional parameter is by default set to False.] 2 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. Leave is the Garfield equivalent of the break statement in C, "break" may be used instead of "Leave" if preferred. [Use of a Leave statement is optional.] 2 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. Iterate is the Garfield equivalent of the continue statement in C, "continue" may be used instead of "Iterate" if preferred. [Use of an Iterate statement is optional.] 1 Global !W
Do not use curly brackets in Global statements. !W
Assigns a value to a global variable, declares a global variable or lists the currently known global variables, depending on the number of arguments. Global "-> algebra -> variables" are used for the "-> algebra -> variables -> substitution" of an expression in input statements and they play a key role in "-> Do" loops, procedure "-> Call"s and in conditionally executed "-> If_line"s and "-> If_block"s. This statement has up to 2 arguments: !Wul_start - the name of a global variable; - the value to be assigned to the global variable. !Wul_end If there are no arguments: All currently defined globals are listed with their type and value. You will see that the list includes a few "-> algebra -> variables -> predefined" globals. Occasionally, you will find globals with names that do not comply with the "-> algebra -> variables -> naming" conventions for variables. These are copies of globals which must be kept even if you modify the original. If you wish to see the value of only a single variable, then use "-> Say". To list all currently known strings, matrices and histograms, use the "-> Call -> LIST_STRINGS", "-> Call -> LIST_MATRICES", and "-> Call -> LIST_HISTOGRAMS" procedures. When the value is omitted: !Wul_start - If the variable already exists, then the Histogram, Matrix or String associated with the variable, if any, is deleted if not referenced elsewhere and the variable is given the value Nill, of type "-> algebra -> variables -> types -> Undefined". - Otherwise, a new variable is created and it is given the value Nill. This amounts to declaring the variable as global, something that is required only in the rare cases where this is explicitly mentioned in the command descriptions. !Wul_end When both a variable name and a value are supplied: !Wul_start - If the variable already exists, then !Wul_start - the expression for the value (2nd argument) is evaluated, using if needed the current value of the variable, this implicitly determines the type that the global variable will have; - if the variable is an Histogram, Matrix or String that is not used elsewhere, then the original contents will be deleted before a new value is assigned; - the value is assigned to the variable. !Wul_end It is permissible to change the type of a variable when changing its value. - Otherwise, a variable with the specified name will be created and it will be given the specified value. The type of the variable is determined by the value. !Wul_end If you wish to use the type of a global variable in a formula, then use either the "-> algebra -> functions -> TYPE" function or the "-> Call -> INQUIRE_TYPE" procedure. Format: !W
  Global "-> Global -> variable" ["-> Global -> value"]
!W
Examples: !W
  Global my_name=`abc DEF`

  Global argon=80
  Global ethane=20
  Global member=`a`/"-> algebra -> functions -> string"(argon)/`e`/string(ethane)
!W
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. 2 variable A character string that satisfies the "-> algebra -> variables -> naming" conventions for variables. This argument should not be an expression. If you really need to update a variable of which the name can only be constructed at run time, then use a construction like the following: !W
  For i From 1 To n Do
     Global {`M`/"-> algebra -> functions -> string"(i)}=i
  Enddo
!W
Note that this will considerably slow down execution of the loop since the expression will be translated at every iteration rather than just once. 2 value The value you wish to give to your global variable must have one of the following formats: !Wul_start - a constant "-> algebra -> variables -> types -> Number" - the True or False "-> algebra -> variables -> types -> Logical" constants - a constant "-> algebra -> variables -> types -> String" - the Nill constant of type "-> algebra -> variables -> types -> Undefined"; - a formula in terms of global variables resulting in any of the known "-> algebra -> variables -> types". !Wul_end To enter a set of numbers into a Matrix, one would normally use the "-> Vector" statement even though one can also use the Global command as illustrated in one of the examples below. Examples: !W
  Global abc `abc`              // Assigns a string to ABC
  Global abc 2<3                // Assigns a logical to ABC
  Global abc "-> algebra -> functions -> string"(2+3)/abc    // Updates the ABC string
  Global abc 1 & 5 & 7          // Assigns a vector to ABC
!W
1 If_block !W
Do not use curly brackets in If, Elseif, Iterate and Leave statements. !W
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: !W
  If "-> If_block -> condition" Then
     "-> If_block -> statements"
  [Elseif condition Then
      statements]
  [Else
      statements]
  Endif
!W
Example: !W
  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
!W
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. 2 condition A constant of type "-> algebra -> variables -> types -> Logical", a variable of type Logical, or an expression that evaluates to a Logical. The statements of the branch are executed if the condition evaluates to True, otherwise they are skipped. 2 statements One or more of the following: !Wul_start - ordinary Garfield commands such as section headers, section commands and sub-section commands; - control structures such as loops, conditional statements and procedure calls !Wul_end The nesting level of If blocks is limited by a compilation parameter which is usually set to 10. 1 If_line !W
Do not use curly brackets in If statements. !W
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: !W
  If "-> If_line -> condition" Then "-> If_line -> statement"
!W
Format 2: !W
  If cond Then ... Do
  
  statement | "-> Do -> Leave" ["-> Do -> var"] | "-> Do -> Iterate" [var]

  Enddo
!W
Examples: !W
  If "-> algebra -> variables -> predefined -> 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 "-> algebra -> functions -> entier"(i/3+0.001)=3 Then "-> Do -> Iterate"
     Say "x+i/3 = {x+i/3}"
  Enddo
!W
2 condition A constant of type "-> algebra -> variables -> types -> Logical", a variable of type Logical, or an expression that evaluates to a Logical. The statements of the branch are executed if the condition evaluates to True, otherwise they are skipped. 2 statement One of the following: !Wul_start - an ordinary Garfield command such as a section header, a section command or a sub-section command; - the start of a loop; - a procedure call. !Wul_end The statement of an If line may not be itself an If line. 1 Parse !W
Do not use curly brackets in Parse statements. !W
This instruction enables you to make input files that prompt for parameters. For instance, in a magnetic field section, you could ask for the value of the magnetic field and then issue a COMPONENTS instruction with the B-field the user specifies. You could also ask the user to enter the name of a cell description and then load it from a library of such descriptions. If you're familiar with REXX, you'll note the similarity with the REXX command by the same name, even if the REXX syntax is far richer than what is offered here. By default, the values found on input are assigned "-> Parse -> Literal"ly to the "-> Global". You can also request evaluation of the input prior to assignment by using the "-> Parse -> Evaluate" option. Format: !W
  Parse ["-> Parse -> Literal" | "-> Parse -> Evaluate"] ...
        {"-> Parse -> Argument" | "-> Parse -> Global" var | "-> Parse -> Input" | "-> Parse -> Terminal" | "-> Parse -> Value" expression} ...
        "-> Parse -> template"
!W
Example 1: Get the piece before and after the decimal dot of pi². !W
  Parse Val pi^2 int'.'frac
!W
Example 2: Ask for a yes/no answer !W
  &FIELD
  Global yes=True
  Global no=False
  Say "Make a 3D plot ? (yes/no)"
  "-> Do -> Until" OK "-> Do"
     Parse Evaluate Terminal plot_3D
     Call inquire_type(plot_3D,type)
     If type=`Logical` Then 
        Global OK=True
     Else
        Say "Please give an answer that evaluates to True or False."
        Global OK=False
     Endif
  Enddo
  If plot_3D Then "-> &FIELD -> plot-field" surface
!W
The usual initialisation files set the global variables YES and NO to respectively True and False. Since we use the Evaluate option, one can simply reply with "yes" or "no" (without typing the quotes), but one may also answer with any expression that evaluates to a "-> algebra -> variables -> types -> Logical" such as 3>4. If the default Literal mode were used, only True and False would be accepted. Example 3: Ask for a cell name !W
  Say "Please enter the name of the cell to be read:"
  Parse Terminal cell
  (The user responds with e.g. DC1)
  get cell.lib {cell}
!W
Here we use the default Literal mode - the response, DC1, will be classified as string and there is no need for quotes. We could also use the Evaluate mode but then reverse "-> introduction -> quotes" would be required around the user response since we do not want DC1 to be evaluated as if it were a global. Example 4: An argument to an input file Assume we have the following input file called "plot_gas": !W
  Parse Arg gas
  Call "-> Call -> inquire_file"(gas/`.gas`,exist)
  If ~exist Then
     Say "{gas}.gas does not exist."
  Else
     &GAS
     get "{gas}.gas"
     opt gas-plot
     &MAIN
  Endif
!W
and a set of gas files with such names as "p10.gas", then we could plot the gas data with a command like: !W
  < plot_gas p10
!W
2 Literal The input elements are processed as-is, without evaluation. A data type is assigned to each element according to the following rules: !Wul_start - "-> algebra -> variables -> types -> Undefined": the input element Nill; - "-> algebra -> variables -> types -> Logical": the input elements True and False; - "-> algebra -> variables -> types -> Number": input elements which have the format [+|-]n[.[n]][E[+|-]n] where n stands for an integer number; - "-> algebra -> variables -> types -> String": all input elements that do not fit in any of the above categories. !Wul_end In most cases, this is what you would intuitively expect to happen. If you use the Literal or Evaluate option, then the option must be placed immediately after the Parse command. Literal and Evaluate are mutually exclusive options. Example: !W
  Global hello `Hello Peter !`
  Parse Literal Value hello . name .
  Say "Person greeted: {name}"
!W
Here, we have to use Literal since the string can not be evaluated: for that, "Hello" would have to be a function, "Peter" an argument hence a Global variable, and the exclamation mark would have to have some algebraic meaning, which it doesn't. [This is default.] 2 Evaluate Requests evaluation of the input data 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 "-> introduction -> quotes": an attempt would be made to evaluate the string as an expression in terms of the global variables. If you use the Literal or Evaluate option, then the option must be placed immediately after the Parse command. Literal and Evaluate are mutually exclusive options. Example: !W
  Say "Open a metafile (yes/no) ?"
  Global yes True
  Global no False
  Global y True
  Global n False
  Parse Evaluate Terminal metafile
  If metafile Then
     Say "Opening metafile {input}.ps ..."
     !add meta type PostScript file-name "{input}.ps"
     !open meta
     !act meta
  Else
     Say "No metafile opened."
  Endif
!W
The If statement expects a Logical as condition. We would however like to offer the user the possibility to reply with "yes" or "no". Therefore, we define Global variables by those names which have the values True and False. With the Evaluate option, a reply of "yes" therefore results in the assignment of Logical value True to the global variable METAFILE. With the Literal option, METAFILE would become a String with value `YES`. [This is not default.] 2 Argument !D1 Obtains the command line !WObtains the !Wcommand line arguments while reading from the main input stream, or the "-> input -> arguments" given after the file name when an external file is "-> input", formats these as a string and uses this string as input for assigning values to the "-> Global" variables of the "-> Parse -> template". Examples: Garfield is started by issuing a command like: !W
  garfield -arg "Hello !"
!W
The double quotes around the argument string are needed only in case of special characters, such as the exclamation mark. Once the program is running, you can access the string "Hello !" with the Parse command: !W
  Parse Arg greeting
  Say {greeting}
!W
Imagine you've an input file called factorial which looks like this: !W
  Parse Arg n
  If "-> algebra -> functions -> type"(n)#`Number` Then
     Say "Please supply a numeric argument."
  Elseif n<1 | abs(entier(n+0.5)-n)>1e-4 Then
     Say "Please supply a strictly positive, integer argument."
  Else
     Global fac=1
     For i From 2 To n Do
        Global fac=fac*i
     Enddo
     Say "Factorial of {n} is {fac}."
  Endif
!W
One would run this file as follows: !W
  
2 Global
  The value of the "-> Global" variable named after Global is retrieved,
  formatted as a string and then used as input.

  Parsing should not give surprising results with Globals that are
  of type "-> algebra -> variables -> types -> Number" or
  "-> algebra -> variables -> types -> String". Globals of type
  "-> algebra -> variables -> types -> Logical" will result in the
  string `True` or `False` while variables of type
  "-> algebra -> variables -> types -> Undefined" yield the string
  `Nill`.

  If the Global variable is an "-> algebra -> variables -> types -> Histogram",
  then the resulting string will be `Histogram`, which is not useful.

  Similarly, a "-> algebra -> variables -> types -> Matrix" with more than
  1 dimension gives the string `n-Matrix` where n is the number of dimensions.
  Only for 1-dimensional matrices will the string contain a formatted portion
  of the matrix. This can be parsed, although not trivially:
!W
  Call "-> Call -> book_matrix"(a,4)
  Parse Global a `(` a `,` b `,` c `,` d `)`
!W


  which is equivalent to:
!W
  Parse Value "-> algebra -> functions -> row"(4) `(` a `,` b `,` c `,` d `)`
!W

2 Input
  A line of input is requested from the regular input stream and this
  line is compared with the template.

  This format is only offered for completeness - the "-> Parse -> Terminal"
  input format is probably more useful. See there for further details.
2 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 single
  and reverse "-> introduction -> quotes" is converted to upper case.

  This is a frequently used format since it permits obtaining user input
  while a file is being "-> input".

  This format can also be used to pause execution of an input file,
  while waiting for the user to hit the return key:
!W
  &FIELD
  grid 5
  print ex,ey
  Parse Terminal dummy
  print v
!W


  The first table will be printed, then the program waits for a response
  from the user and the 2nd table is printed only after the return key has
  been pressed.
2 Value
  The expression is evaluated in terms of "-> Global" variables,
  the result is formatted as a string and the result is compared
  with the template. 

  This format is similar to Parse "-> Parse -> Global", see there
  for examples and further comments.
2 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:

!Wtable_start
!T+P           +                                                .
  --------------------------------------------------------------
  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.
  --------------------------------------------------------------
!Wtable_end

  All elements can be repeated many times. 

  Instead of reverse "-> introduction -> 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.

  If there are more variables in the template than elements in the
  input, then the variables to which no value can be assigned will
  be set to have type "-> algebra -> variables -> types -> Undefined".
  Conversely, if there are more elements than variables, then all
  variables will together, with their separators, be assigned to the
  last variable. This operation is likely to fail in the Evaluate
  mode.

  Examples with option "-> Parse -> Literal":

!Wtable_start
!T+P          +P            +                                   .
  --------------------------------------------------------------
  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=`x+1`
  1 2 3 4     x y .         x=1, y=2
  1 2         x y z         x=1, y=2, z=Nill
  1 2 3       x y           x=1, y=`2 3`
  1 2 A 3     x . `A` y     x=1, y=3
  1 2 A 3     x `A` y       x=`1 2`, y=3
  1 `abc` 2   x y .         x=1, y=`abc`
  1>2         z .           z=`1>2`
  --------------------------------------------------------------
!Wtable_end

  Examples with option "-> Parse -> Evaluate":

!Wtable_start
!T+P          +P            +                                   .
  --------------------------------------------------------------
  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=Nill
  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
  --------------------------------------------------------------
!Wtable_end
1 Say
  The Say command outputs the string that follows it, performing 
  "-> algebra -> variables -> substitution" of expressions in terms
  of "-> Global" variables.

  Format:
!W
  SAY string
!W


  Example:
!W
  Say "Only {"-> algebra -> variables -> predefined -> time_left"} seconds left !"
!W

  Prints the value of a "-> algebra -> variables -> predefined"
  global variable.
1 Vector
  Creates a new 1-dimensional "-> algebra -> variables -> types -> Matrix",
  also called vector, or reads new data into an already existing Matrix.
  Matrices contain exclusively numeric data.

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

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

  For higher dimensional already existing Matrices,
  the number of dimensions and the size are kept as they were, and 
  new elements replace old elements in the order in which the Matrix 
  is internally stored (opposite to the Fortran convention).

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

  The Vector statement can read data into one or more Matrices at the
  time. If more than one Matrix is present, then the statement should
  be followed by a series of lines which contain precisely one new
  element of each of the Matrices. If only one Matrix is present, then
  one may type an arbitrary number of elements on an arbitrary number
  of lines following the statement. In either case, there should be
  a blank line to signal that all elements have been entered.

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

  Format:
!W
  Vector x y z ...              Vector x
  x1 y1 z1 ...                  x1 x2 x3 ... 
  x2 y2 z2 ...                  ...
  ...                           ...
  xn yn zn ...                  ... xn
  (blank line)                  (blank line)
!W


  Example 1:
!W
  Vector zzz
  0 1 2 3 4 5 6
  
  Call reshape_matrix(zzz,2,4,pi)
!W

  The Vector statement results in a 1-dimensional matrix of length 7, 
  called ZZZ, which contains the numbers 0 to 6. 
  The "-> Call -> RESHAPE_MATRIX" procedure call re-arranges this vector
  to a 2\×4 matrix. This matrix has one element more than the original
  vector, which is filled with the value PI, which is one of the pre-defined
  "-> algebra -> variables -> constants".

  We could have written the Vector statement using the concatenation 
  "-> algebra -> operator" & and the "-> algebra -> functions -> ROW"
  function:
!W
  Global zzz = 0 & "-> algebra -> functions -> row"(6)
!W


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

  // Note the empty line
!W

  Here, we enter a table (an extract from the Krause fluorescence
  and Coster-Kronig yields tables) copied from a paper, without having to
  manually remove the names of the elements. This is done by declaring
  the field of the element name as "dummy".
2 variable
  Variables assigned with the Vector statement must follow the
  "-> algebra -> variables -> naming" convention for global variables.

  If the name of the variable is already in use for a variable of
  another data type, then the value the variable had before the Vector
  statement is lost.
1 algebra
  Garfield can evaluate certain formulae with symbolic parameters 
  without need for external compilation and linking. Although the
  use of formulae is fairly intuitive, it may be useful for some
  applications to have good understanding of the way formulae are
  dealt with.

  Formulae can be typed as usual in Fortran or C, with some exceptions:
!Wul_start
  * Identifiers (symbolic names for "-> algebra -> variables") are up
    to 10 characters long and should follow a set of
    "-> algebra -> variables -> naming" conventions.

  * The "-> algebra -> operator"s follow mostly the Fortran notation,
    C users will note a few additional operators such as power raising.
    Fortran users should note that the meaning of the operators depends
    on the type of the operands.

  * Not all the Fortran intrinsic "-> algebra -> functions" are
    available and some intrinsic functions have a different name.
    Garfield has a reasonable collection of random number generators.

  * The data "-> algebra -> variables -> types" differ from those
    found in C and Fortran. Moreover, variables know their type and
    different versions of the operators and functions are used
    depending on the type of the variable. The type can change during
    execution, e.g. when a value of a different type is assigned to
    a variable.

  * Blanks are significant separators, e.g. 'EXP X' is an acceptable
    formula (the quotes serve to keep the string together).
!Wul_end

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

  The translation of the formula into an instruction list, is done
  independent of the data type. It may also be possible that the 
  resulting instruction list can be executed for several data types.

  Instruction lists can be edited in the algebra editor which is
  entered by typing a @ instead of a formula. The editor behaves like
  a subsection. On exit of the editor, the function is used by the
  calling routine to perform its task.
2 variables
  In Garfield input, one makes frequent use of variables. For instance,
  when you make a contour plot of the electrostatic potential, you type
!W
  PLOT CONTOUR V
!W


  The "V" in this statement is a local variable of the "-> &FIELD -> PLOT-FIELD" command
  which equals the electrostatic potential at a given point. The name
  and value of these variables is not under your control. Moreover,
  you usually only have access to them in the context of the command
  being executed.

  Garfield also has variables which are entirely under your control:
  you choose their name and value, you determine when expressions are
  to be evaluated, and you decide when and how to display their values.
  These are called global variables, or "-> Global"s 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.

  Global variables can be used for a variety of things:
!Wul_start
  - doing ordinary arithmetic;
  - constructing a "-> Do" loop;
  - as conditions of "-> If_block"s and "-> If_line"s;
  - as arguments in "-> Call";
  - to receive the result of "-> Parse";
  - "-> algebra -> variables -> substitution" of expressions
    in ordinary commands.
!Wul_end
3 creating
  The values of local variables are always set by the program - you
  can not change their values nor their name.

  In contrast, you can create and (in most cases) modify "-> Global" variables.
  There are many methods to create them:
!Wul_start
  - by applying arithmetic to existing variables;
  - by using the "-> Global" command to create variables of the types
    "-> algebra -> variables -> types -> Logical";
    "-> algebra -> variables -> types -> Matrix",
    "-> algebra -> variables -> types -> Number",
    "-> algebra -> variables -> types -> String",
  - by using the "-> Vector" command or functions like
    "-> algebra -> functions -> ROW",
    "-> algebra -> functions -> ONES" and
    "-> algebra -> functions -> ZEROES" to create
    a 1-dimensional
    "-> algebra -> variables -> types -> Matrix" or the
    "-> Call -> BOOK_MATRIX" procedure to create Matrices of
    any shape;
  - by using the concatenation "-> algebra -> operator" & to
    create a Matrix from one or more Numbers;
  - by calling "-> Call -> BOOK_HISTOGRAM" to make an
    "-> algebra -> variables -> types -> Histogram";
  - by invoking commands that store part of their output in globals,
    e.g. the "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION -> KEEP-RESULTS"
    option of the ARRIVAL command.
!Wul_end

  Also some global variables are defined by the program:
!Wul_start
  - some globals are "-> algebra -> variables -> predefined";
  - loop variables of "-> Do" loops and the arguments of
    "-> Call" statements are automatically declared as globals.
!Wul_end
3 naming
  Global variable names must satisfy the following conventions:

!Wul_start
  - length up to 10 characters;
  - first character is upper case alphabetic;
  - none of the following "-> algebra -> operator"s:
!Wul_start
    + numeric operators: + - * /
    + logical operators: & |
    + negation: ^
    + comparison operators: < = # >
!Wul_end
  - no punctuation: , . : ;
  - no "-> introduction -> brackets": ( [ { ) ] }
  - no "-> introduction -> quotes": ' " `
  - no blanks.
!Wul_end

  Examples:
!W
  "-> Global" a_1 = 5
  Global abc = `This is a string`
  Global v="-> algebra -> functions -> row"(20)
!W


  Although permitted, it is not advisable to force variable names
  to contain lower case characters as in the following:
!W
  // Not recommended
  Global "Abc" 123
!W

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 
  "-> algebra -> variables -> types -> Number",
  "-> algebra -> variables -> types -> Logical" or
  "-> algebra -> variables -> types -> String", then
  the value is simply substituted. If the result is an
  "-> algebra -> variables -> types -> Histogram", 
  then the string "Histogram" is substituted for the formula.
  For a 1-dimensional "-> algebra -> variables -> types -> 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 misused, in particular they
  should never be used in "-> Do" loops, in the conditions of
  "-> If_line"s and "-> If_block"s, in the arguments of procedure
  "-> Call"s, 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 "-> introduction -> brackets".

  Format: 
!W
  any text {formula} more text
!W


  Example:
!W
  Global a=60
  Say "Tangent of {a} degrees is {tan(pi*a/180)}."
!W


  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.
!W
  // What one should not do
  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
!W


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

!Wtable_start
!T+S            +                                            R       .
  -------------------------------------------------------------------
  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
  -------------------------------------------------------------------
!Wtable_end

  The mode is a numeric equivalent of the type, the mode is used
  only internally for quick reference.
4 Undefined
  A variable has type Undefined if:
!Wul_start
  - it has been given the value Nill, the only value possible
    for variables of this type;
  - it has been created but not yet been given a value;
  - it results from certain kinds of arithmetic errors;
  - it has been "touched" by a variable of type Undefined.
!Wul_end

  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 "-> algebra -> functions -> TYPE" function.

  One of the pre-defined "-> algebra -> variables -> constants" is
  of this type: NILL.
4 String
  Strings are character sequences.

  Strings are usually created by enclosing a series of characters
  in reverse "-> introduction -> quotes", as illustrated in the
  examples below.

  Strings can be concatenated with the / "-> algebra -> operator" and can be
  lexically compared with each other using the >, < and = operator. The functions
  "-> algebra -> functions -> NUMBER" and
  "-> algebra -> functions -> STRING" convert Strings to
  "-> algebra -> variables -> types -> Number"s and vv.
  There is also a series of procedures that act on Strings:
  "-> Call -> STRING_DELETE", "-> Call -> STRING_INDEX", 
  "-> Call -> STRING_LENGTH", "-> Call -> STRING_LOWER", 
  "-> Call -> STRING_MATCH", "-> Call -> STRING_PORTION", 
  "-> Call -> STRING_REPLACE", "-> Call -> STRING_UPPER",
  "-> Call -> STRING_WORD" and "-> Call -> 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. One does not declare the length of Strings since
  the length is implied by the initialisation and operations the
  string has undergone. The length of a string can vary in time.

  There are no constant strings, but there are 
  "-> algebra -> variables -> predefined" globals of type String.

  Examples:
!W
  "-> Global" gas_file `gas.dat`

  Global p=1
  Global gas_file `gas_p`/"-> algebra -> functions -> string"(p)/`.gas`
!W

4 Number
  Numbers are stored in single machine precision.
  No distinction is made between reals and integers.
  Thus, they are the equivalent of INTEGER and REAL
  combined in Fortran and of float and int in C.

  The numbers 0, 1, 2 and PI are "-> algebra -> variables -> constants",
  there are also "-> algebra -> variables -> predefined" globals of this
  type.
4 Logical
  There are only 2 logical values: True and False. They are written
  as such, without the dots that are used in Fortran. There is no C
  equivalent of this data type; instead C uses the integer value 1
  to represent True and 0 for False.

  Both True and False are stored as "-> algebra -> variables -> constants"
  and there are several "-> algebra -> variables -> predefined" globals of
  this type. Logicals can also be created by applying a comparison 
  "-> algebra -> operator" to variables of other data types:
!W
  Global equal `aaa`=`a`/`aa`
  Global bigger 5>2^2
!W


  Logicals can be acted upon with operators, as & (and) and | (or)
  as well as with the "-> algebra -> functions -> NOT",
  "-> algebra -> functions -> STRING" and 
  "-> algebra -> functions -> TYPE"
  "-> algebra -> functions".

  Logicals are commonly used in the conditions of "-> If_line"s,
  "-> If_block"s and "-> Do" loops:
!W
  "-> Do"
     "-> Say" "Quit ? Please reply with True or False"
     "-> Parse" terminal quit
     If "-> algebra -> functions -> type"(quit)#`Logical` Then
        Say "Please answer with True or False"
     Elseif quit Then
        Say "Quit"
        Leave
     Endif
  Enddo
!W


  Logicals in Garfield are not equivalent to numbers, i.e. one can
  not normally replace True by 1. Similarly, one can not apply
  mixed arithmetic between Logicals and Numbers.
4 Histogram
  Histograms are used to investigate statistical properties of
  a quantity, e.g. the distribution of the gain in an RPC or the
  arrival time distribution in a drift chamber. Histograms consist
  of a series of so-called bins, which each count the number of
  times the quantity being histogrammed has a value in the range
  covered by the bin.

  Garfield histograms are currently 1-dimensional only, and they
  have adjacent, equal size bins. They come in 2 flavours:
!Wul_start
  - histograms with a user defined range;
  - autorange histograms.
!Wul_end
  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
  "-> Call -> BOOK_HISTOGRAM -> options -> 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 are usually created with a call to
  "-> Call -> BOOK_HISTOGRAM". Several instructions
  can generate histograms as part of their output.

  Histograms can be subject of most of the ordinary arithmetic
  "-> algebra -> operator"s and "-> algebra -> functions". Mixed
  arithmetic between "-> algebra -> variables -> types -> Number"s
  and histograms is permitted and results in histograms.

  Example:
!W
  Call "-> Call -> get_histogram"(part1,`file1.hist`,`delay`)
  Call "-> Call -> get_histogram"(part2,`file2,hist`,`delay`)
  Call "-> Call -> get_histogram"(part3,`file3,hist`,`delay`)
  Global delay=(part1+part2+part3)/3
!W

  Each of a series of jobs, run in parallel, has created an histogram
  called DELAY, filled it, and written it to a file. The histograms
  from the 3 files are retrieved and averaged.

  Histograms can also be operated on by a series of procedures,
  For instance, histograms can, by means of the
  "-> Call -> 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.
4 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:
!Wul_start
  - "-> Call -> BOOK_MATRIX" creates an empty matrix of any shape;
  - 1-dimensional matrices filled with a series of numbers
    are more conveniently made with the "-> Vector" command;
  - in expressions, the "-> algebra -> functions -> ROW" function
    stands for the sequence of numbers 1,\ 2,\ 3,\ ...\ n;
  - concatenation of two "-> algebra -> variables -> types -> Number"s
    with the concatenation "-> algebra -> operator"\ &, results 
    in a Matrix;
  - some instructions produce matrices as part of their output.
!Wul_end

  The usual arithmetic "-> algebra -> operator"s and 
  "-> algebra -> functions" can be applied to matrices as if they
  were numbers. Mixed arithmetic between 
  "-> algebra -> variables -> types -> Number"s and matrices is
  permitted and results in matrices. Applying arithmetic to entire
  matrices is much faster than looping over the elements.

  Parts of matrices can be addressed with the following syntax:
!Wul_start
  - the name of the matrix is followed by an indexing expression
    that is enclosed between [\ and\ ];
  - when indexing an n-dimensional matrix, the indexing expression
    contains precisely n semi-colon separated parts, one along
    each dimension of the matrix;
  - each part consists of 0 or more comma separated Numbers
    which will act as indices, or a mixture of 1-dimensional
    Matrices and Numbers;
  - if a part is left empty, then the entire range is selected.
!Wul_end

  Some examples for a 1-dimensional matrix:
!W
  A = (9 8 7)     A[1,2,3,1] = (9 8 7 9)      A[1+"-> algebra -> functions -> ROW"(2)] = (8 7)
!W

  The "-> algebra -> functions -> ROW" function returns a 1-dimensional
  Matrix that contains the numbers 1 to the value of the argument, in
  this case the numbers 1 and 2. Indexing using 1-dimensional matrices 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:
!W
  "-> Global" x=-pi+2*pi*("-> algebra -> functions -> row"(500)-1)/499
  Global y="-> algebra -> functions -> cos"(x)
  "-> Call" "-> Call -> fit_polynomial"(x[200+"-> algebra -> functions -> row"(100)],y[200+"-> algebra -> functions -> row"(100)],0.001, ...
     a0,a1,a2,ea0,ea1,ea2,`plot`)
!W


  When indexing a 2-dimensional matrix, one needs a semi-colon to
  separate the indices along the 1st and 2nd dimension. Remember that
  an empty indexing part selects that entire dimension:
!W
      ( 1 2 3 )             ( 3 2 )
  A = ( 2 4 6 )   A[3,2;] = ( 6 4 )     A[;1] = ( 1 2 3 )
      ( 3 6 9 )             ( 9 6 )
!W


  Notes:
!Wol_start
  1. Addressing outside the array bounds is not permitted.
  2. A 2\×3-Matrix is not, as in Fortran, equivalent to a 
     6-Matrix - the indexing expression consists of 2 parts
     in a 2\×3-Matrix and of only 1 part in a 6-Matrix.
  3. Keep in mind that the number of dimensions does not change,
     A[;1] is a 2-dimensional matrix ! Use "-> Call -> RESHAPE_MATRIX" if
     you wish to transform a 1\×n-matrix to an n-matrix, or use the 
     "-> algebra -> functions -> NUMBER" function to change a 
     1\×1\×...\×1-matrix to a number.
!Wol_end

3 storage
  Every "-> algebra -> variables -> types -> Histogram",
  "-> algebra -> variables -> types -> Logical",
  "-> algebra -> variables -> types -> Matrix",
  "-> algebra -> variables -> types -> Number" and
  "-> algebra -> variables -> types -> 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 
  "-> algebra -> variables -> constants" that are
  not affected by the execution of the instruction
  list.
3 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 the values of the registers R(0) to R(-6) is not
  by itself 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:

!Wtable_start
!T+P         +P      +            +                                              .
  -------------------------------------------------------------------------------
  Location   Name    Value        Type
  -------------------------------------------------------------------------------
  R(0)       0       0            "-> algebra -> variables -> types -> Number"
  R(-1)      1       1            "-> algebra -> variables -> types -> Number"
  R(-2)      2       2            "-> algebra -> variables -> types -> Number"
  R(-3)      PI      3.14159265   "-> algebra -> variables -> types -> Number"
  R(-4)      FALSE   False        "-> algebra -> variables -> types -> Logical"
  R(-5)      TRUE    True         "-> algebra -> variables -> types -> Logical"
  R(-6)      NILL    Nill         "-> algebra -> variables -> types -> Undefined"
  -------------------------------------------------------------------------------
!Wtable_end

  Notes:
!Wol_start
  1. The values for False and True are internally represented as
     0 and 1 respectively, but arithmetic between Logicals and
     Numbers is not encouraged.
!Wol_end
3 predefined
  Some global variables are defined during the initialisation phase and
  they are kept up to date automatically. Most of these variables can not
  be modified by the user.

!Wtable_start
!T+PS        +        +                                               .
  --------------------------------------------------------------------
  Global     Type     Explanation
  --------------------------------------------------------------------
  BATCH      Logical  True if running in batch, False otherwise.
  FRAME      Number   Sequential number of the plot frame
  INPUT      String   Name of the current input stream.
  INTERACT   Logical  True if running interactively, False otherwise.
  MACHINE    String   The type of computer on which you're running.
  OK         Logical  True if last algebra instruction was successful.
  OUTPUT     String   Name of the current output stream.
  TIME_LEFT  Number   The amount of CPU time that remains [sec].
  X          Number   Used for fitting
  --------------------------------------------------------------------
!Wtable_end
4 BATCH
  A global variable of type "-> algebra -> variables -> types -> Logical"
  which is set to True if Garfield is currently run in batch and which
  is set to False if the program runs interactively.

  A program is said to run in batch if the standard input stream is
  anything else than terminal input. For instance, running under Unix
  with input taken from a file (e.g. by typing garfield < input) will
  result in BATCH being set to True.
4 FRAME
  Stores the sequential "-> algebra -> variables -> types -> Number" of
  the plot frame. The first frame produced during a run has number 1,
  the number is incremented by one every time a new frame is opened.

  This variable is meant to be used in conjunction with the 
  "-> graphics -> ADD-WORKSTATION -> SINGLE-FRAME-FILE" option
  when opening a workstation which should only receive one frame
  per file, such as an Encapsulated PostScript file.

  You may change the value of this variable, but not its type.
4 INPUT
  A "-> algebra -> variables -> types -> String" that contains the name
  of the current input file.

  The variable has a value of "Standard input" when input comes from
  standard input. The value changes while an initialisation file is read,
  and also whenever you use "-> input" redirection.

  This variable can be used to construct automatically a name for a
  metafile:
!W
  If input#`Standard input` Then
     !add meta type PostScript file-name "{input}.ps"
     !open meta
     !act meta
  Else
     !add meta type PostScript file-name "garfield.ps"
     !open meta
     !act meta
  Endif
!W

4 INTERACT
  A global variable of type "-> algebra -> variables -> types -> Logical"
  which is set to False if Garfield is currently run in batch and which
  is set to True if the program runs interactively.

  A program is said to run interactively if the standard input stream is
  terminal input. INTERACT will be set to True if you start Garfield by
  simply typing the name of the executable, but INTERACT will be set to
  False if input is taken from a file (e.g. by typing garfield < input).
4 MACHINE
  A global variable of type "-> algebra -> variables -> types -> String"
  which contains the type of computer for which the executable has been
  produced.

  Currently, the following values can be returned:

!Wtable_start
!T+P             +                                          .
  ----------------------------------------------------------
  Value          Meaning
  ----------------------------------------------------------
  Apollo         Apollo systems running SR 10
  CMS            VM/CMS, an IBM operating system
  Cray           Cray running UNICOS
  MVS            MVS, an IBM operating system
  Vax            Vax or Alpha systems running VMS or OpenVMS
  Unix           Various Unix systems, including Linux
  < not known >  Unidentified system
  ----------------------------------------------------------
!Wtable_end
4 OK
  A "-> algebra -> variables -> types -> Logical" that tells whether
  the last algebraic operation was successful.

  Most procedures and also several regular commands set this variable
  depending on the success of the calculations requested.
4 OUTPUT
  A "-> algebra -> variables -> types -> String" that contains the name
  of the current output file.

  The variable has a value of "Standard output" when output is sent to
  the standard output stream. The value changes whenever you use "-> output"
  redirection.
4 TIME_LEFT
  The time left, expressed in seconds.

  Time limits are relevant mostly while running in batch and checking
  this variable permits graceful termination of iterative calculations.

  This variable is of type "-> algebra -> variables -> types -> Number".
4 X
  A parameter used amongst others by the "-> Call -> FIT_FUNCTION" procedure.

  This is a "-> algebra -> variables -> types -> Number" which may be
  modified by the user, but its value can at any moment be overwritten
  by the program.
2 operator
  A single operator symbol in Garfield can have a meaning which
  depends on the type of its operands - i.e. the operators can be
  overloaded. For instance, the "+" operator adds numbers, acts
  as 'or' between logicals, and concatenates strings.

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

  Garfield recognises the following binary operators:

!Wtable_start
!T+P          RP        RP      +                        .
  -------------------------------------------------------
  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----   concatenate strings
  **, ^         -N-HM    same   exponentiation
  &             --L--   --L--   and
  &             -N--M   ----M   concatenate matrices
  &             S----   S----   concatenate strings
  |             --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
  -------------------------------------------------------
!Wtable_end

  Unary operators are treated like functions, and therefore
  have higher precedence than binary operators. As a result,
  '-x^2' is always positive. The following unary operators
  are currently known:

!Wtable_start
!T+P          RP        RP      +                        .
  -------------------------------------------------------
  Operator    Acts on   Gives   Effect
  -------------------------------------------------------
  +             -N-HM    same   assignment
  -             -N-HM    same   negative
  ^, ~          --L--   --L--   not
  -------------------------------------------------------
!Wtable_end

  Notes:
!Wol_start
  1. The operators act element by element on variables of type 
     "-> algebra -> variables -> types -> Histogram" and
     "-> algebra -> variables -> types -> Matrix".
  2. The sorting sequence for characters in
     "-> algebra -> variables -> types -> String"s depends on
     the computer system that is used.
  3. Mixed operations between 
     "-> algebra -> variables -> types -> Number" and Histograms
     or between Numbers and Matrices result in Histograms and 
     Matrices respectively.
  4. All operators can be applied to type 
     "-> algebra -> variables -> types -> Undefined", the result
     being Undefined.
  5. The equality and non-equality operators have a tolerance
     of 10\-4\ on all computers except Cray where a tolerance of
     10\-8\ is used.
  6. Fortran users should be aware that the double slash stands
     for a "-> comment" in-line comment for Garfield, not for the
     string concatenation operator. Strings are concatenated in
     Garfield with a single slash.
!Wol_end
2 functions
  Garfield currently recognises the following intrinsic functions:

!Wtable_start
!T+PS           RP        RP      +                              .
  ---------------------------------------------------------------
  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
  EXIST           S----   --L--   existence of a file
  EXP             -N-HM    same   exponential
  GAMMA           -N-HM    same   \Γ-function
  GLOBAL          S----     any   global with name of the string
  LANDAU          -N-HM    same   Landau density function
  LOG             -N-HM    same   logarithm
  LOG_GAMMA       -N-HM    same   logarithm of \Γ-function
  MAXIMUM         ---HM   -N---   maximum of matrix or histogram
  MEAN            ---HM   -N---   mean of a matrix or histogram
  MINIMUM         ---HM   -N---   minimum of matrix or histogram
  NOT             --L--   --L--   negation of logical value
  NUMBER          S---M   -N---   conversion to a number
  ONES            -N---   ----M   row of 1's
  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
  REVERSE         ----M   ----M   reverse order in a matrix
  RMS             ---HM   -N---   RMS of a matrix or histogram
  ROW             -N---   ----M   row of number 1 to argument
  SIN             -N-HM    same   sine
  SINH            -N-HM    same   hyperbolic sine
  SIZE            ----M   -N---   total number of elements
  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
  ZEROES          -N---   ----M   row of 0's
  ---------------------------------------------------------------
!Wtable_end

  In addition, the following random number generators are known:

!Wtable_start
!T+PS               R           +                                       .
  ----------------------------------------------------------------------
  Function           Argument   Effect
  ----------------------------------------------------------------------
  RND_EXPONENTIAL        mean   Exponential distribution with given mean
  RND_FUNCTION              -   Random number according to a function
  RND_GAMMA              mean   \Γ-distribution with given mean 
  RND_GAUSS                 -   Normal distribution N(0,1)
  RND_HISTOGRAM     histogram   Random number according to an histogram
  RND_LANDAU                -   Landau distribution
  RND_LAPLACE           width   Laplace distribution
  RND_POISSON            mean   Poisson distribution with given mean
  RND_POLYA          \θ   Polya distribution with given \θ
  RND_UNIFORM         scaling   Uniform distribution
  ----------------------------------------------------------------------
!Wtable_end

  Notes:
!Wol_start
  1. The functions act element by element on arguments of type
     "-> algebra -> variables -> types -> Histogram" and
     "-> algebra -> variables -> types -> Matrix".
  2. All functions can be applied to type 
     "-> algebra -> variables -> types -> Undefined", the result
     being Undefined.
  3. Further random number generators are available as procedures:
     "-> Call -> RND_MULTIPLICATION" and "-> Call -> RND_VAVILOV".
  4. Further functions and random number generators can be added
     on request.
  5. More elaborate operations are available as procedures "-> Call"s.
!Wol_end
3 ABS
  Returns the absolute value.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCCOS
  Returns an angle such that cos(angle) equals the argument.

  The angle is expressed in radians.

  The absolute value of the argument, or of each element of the
  argument, should be less than or equal to 1.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCCOSH
  Returns a value such that cosh(value) equals the argument.

  The argument, or each element of the argument, should be equal to
  or larger than 1.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCSIN
  Returns an angle such that sin(angle) equals the argument.

  The angle is expressed in radians.

  The absolute value of the argument, or of each element of the
  argument, should be less than or equal to 1.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCSINH
  Returns a value such that sinh(value) equals the argument.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCTAN
  Returns an angle such that tan(angle) equals the argument.

  The angle is expressed in radians.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ARCTANH
  Returns a value such that tanh(value) equals the argument.

  The absolute value of the argument, or of each element of the
  argument, should be less than 1.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 COS
  Returns the cosine of an angle, which should be expressed
  in radians.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 COSH
  Returns the hyperbolic cosine of the argument.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 ENTIER
  Returns the largest integer smaller than or equal to the argument.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 EXIST
  Returns True if the file given as argument exists, otherwise
  it returns False.

  This function is equivalent to the "-> Call -> INQUIRE_FILE"
  procedure call.

  The argument must be of type "-> algebra -> variables -> types -> String".
3 EXP
  Returns e to the power of the argument.

  The argument, or, in case of an argument of type matrix or histogram,
  all elements of the argument, should be less than the compilation 
  parameter EXPMAX. An exponential overflow error condition is raised
  if this condition is not fulfilled.
  The exponential of an argument or an element of the argument
  less than -EXPMAX will be set to 0 if the
  "-> algebra -> OPTIONS -> IGNORE-EXPONENTIAL-UNDERFLOW" option has been set.
  Otherwise an exponential underflow error condition is raised.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 GAMMA
  Returns the \Γ-function of the argument. The \Γ-function is
  the real number extension of the factorial: \Γ(x) = (x-1)!

  The argument, or each element of the argument, should be 
  larger than 10\-20\ and smaller than 25. In expressions where
  the \Γ-function is cancelled in part by other exponentials,
  and in which arguments larger than 25 are required, one should
  use the "-> algebra -> functions -> LOG_GAMMA" function.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 GLOBAL
  GLOBAL is a function that takes a
  "-> algebra -> variables -> types -> String"
  as argument and which returns the value of the global variable
  by the same name.

  The function returns Nill, of type
  "-> algebra -> variables -> types -> Undefined",
  if there is no such global variable.

  Example:
!W
  "-> Global" i=1
  "-> Do"
     If "-> algebra -> functions -> type"("-> algebra -> functions -> global"(`SEL_`/"-> algebra -> functions -> string"(i)))#`Histogram` Then Leave
     Call "-> Call -> write_histogram_rz"(global(`SEL_`/string(i)),`arrival.rz`)
     Global i=i+1
  Enddo
!W

  
  The "-> &DRIFT -> ARRIVAL-TIME-DISTRIBUTION" command can create a set
  of histograms which are numbered SEL_1, SEL_2 etc. These histograms
  are written to an RZ file by the above set of instructions. The
  "-> algebra -> functions -> TYPE" and GLOBAL functions are used to
  stop the loop as soon as the last histogram has been written.
3 LANDAU
  Returns the Landau density function.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 LOG
  Returns the (natural) logarithm of the argument.

  The argument, or each element of the argument, should be larger than 0.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 LOG_GAMMA
  Returns the logarithm of the \Γ-function of the argument. The 
  \Γ-function is the real number extension of the factorial:
  \Γ(x)\ =\ (x-1)! 

  This function is used when the \Γ-function itself can't be
  evaluated without numerical overflow, but when the overflow
  in the expression as a whole is cancelled by other terms. If the
  argument is in the range [10\-20\,25], then one would normally use
  the "-> algebra -> functions -> GAMMA" function directly.

  The argument, or each element of the argument, should be strictly
  positive. 

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 MAXIMUM
  The MAXIMUM function can take either an
  "-> algebra -> variables -> types -> Histogram" or a
  "-> algebra -> variables -> types -> Matrix" as argument.
  A Matrix-type argument may have any number of dimensions.
  This function will also find the largest of a set of
  "-> algebra -> variables -> types -> Number"s: using the
  concatenation "-> algebra -> operator" &, one transforms
  the set of numbers into a Matrix. See the example for
  "-> algebra -> functions -> MINIMUM".

  When given an Histogram, it will return the coordinate of the upper
  edge for the last bin. Using this function with an Histogram is
  equivalent to calling the
  "-> Call -> INQUIRE_HISTOGRAM" procedure and using its
  "-> Call -> INQUIRE_HISTOGRAM -> maximum" argument.

  When given a Matrix as argument, it will return the largest value
  found in the Matrix. To obtain the indices of the maximum, use the
  "-> Call -> LOCATE_MAXIMUM" procedure call.

  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number". 
3 MEAN
  Returns the mean of an "-> algebra -> variables -> types -> Histogram"
  or a "-> algebra -> variables -> types -> Matrix".

  Using this function with an Histogram is equivalent to calling the
  "-> Call -> INQUIRE_HISTOGRAM" procedure and using its
  "-> Call -> INQUIRE_HISTOGRAM -> mean" argument.

  This function accepts Matrices with any number of dimensions.

  The mean is for both Histograms and Matrices defined as:
!W
          \Σ x
  mean  = ---
           n
!W


  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number".

  Example:

  See the "-> algebra -> functions -> RMS" function.
3 MINIMUM
  The MINIMUM function can take either an
  "-> algebra -> variables -> types -> Histogram" or a
  "-> algebra -> variables -> types -> Matrix" as argument.
  A Matrix-type argument may have any number of dimensions.
  This function will also find the smallest of a set of
  "-> algebra -> variables -> types -> Number"s: using the
  concatenation "-> algebra -> operator" &, one transforms
  the set of numbers into a Matrix. See the example.

  When given an Histogram, it will return the coordinate of the lower
  edge for the first bin. Using this function with an Histogram is
  equivalent to calling the
  "-> Call -> INQUIRE_HISTOGRAM" procedure and using its
  "-> Call -> INQUIRE_HISTOGRAM -> minimum" argument.

  When given a Matrix as argument, it will return the smallest value
  found in the Matrix. To obtain the indices of the minimum, use the
  "-> Call -> LOCATE_MINIMUM" procedure call.

  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number".

  Example: finding the smallest of a set of numbers
!W
  Global x1 = 2
  Global x2 = 3
  Global x3 = 1
  Global x4 = 1.5
  Global xmin = minimum(x1 & x2 & x3 & x4)
  Say "The smallest of the numbers ({x1,x2,x3,x4}) is {xmin}."
!W

3 NOT
  Logical negation of the argument.

  The function takes a
  "-> algebra -> variables -> types -> Logical" are argument
  and returns a Logical.
3 NUMBER
  Converts a variable of type 
  "-> algebra -> variables -> types -> Matrix" or
  "-> algebra -> variables -> types -> String"
  to a variable of type 
  "-> algebra -> variables -> types -> 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.
3 ONES
  Returns a 1-dimensional
  "-> algebra -> variables -> types -> Matrix"
  which contains n times the number 1, where n is the argument.
  The argument n is mandatory and should be of type
  "-> algebra -> variables -> types -> Number".

  Use the "-> algebra -> functions -> ZEROES" function to
  create a vector than contains 0 everywhere and the
  "-> algebra -> functions -> ROW" function if you
  wish to create a vector that contains the numbers 1, 2, 3 ...
3 PRODUCT
  Returns the product of all channels of an
  "-> algebra -> variables -> types -> Histogram" or of all
  elements of a
  "-> algebra -> variables -> types -> Matrix".

  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number". 
3 REFERENCE
  Returns the reference number of a
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> String".

  This is the reverse operation of the
  "-> algebra -> functions -> REF_HISTOGRAM",
  "-> algebra -> functions -> REF_MATRIX" and
  "-> algebra -> functions -> REF_STRING".
3 REF_HISTOGRAM
  "-> algebra -> variables -> types -> Histogram"s are usually
  accessed via the "-> Global" variable with which they are associated.

  Internally however, the bookkeeping of histograms and of global
  variables are separated, and it is common that histograms exist
  which have no associated global. In the rare event that one
  wishes to access these histograms one uses REF_HISTOGRAM.

  REF_HISTOGRAM takes a "-> algebra -> variables -> types -> Number"
  as argument which is interpreted as the number of the histogram in
  the histogram buffer. The numbers of the histograms can be found in
  the first column of the output of the "-> Call -> LIST_HISTOGRAMS"
  procedure.

  Example:
!W
  Call "-> Call -> delete_histogram"
  Call "-> Call -> book_histogram"(a,25,`integer`)
  For i From 1 To 10000 Do
     Call "-> Call -> fill_histogram"(a,rnd_poisson(3))
  Enddo
  Call "-> Call -> plot_histogram"(ref_histogram(1))
  Call "-> Call -> plot_end"
!W


  By first calling "-> Call -> DELETE_HISTOGRAM", we are sure that
  the next histogram to be booked will have number 1. This histogram
  is in this case also known as A. It is filled and then plotted,
  using its number rather than its associated global.
3 REF_MATRIX
  Gives access to a "-> algebra -> variables -> types -> Matrix"
  by the internal reference number.

  Such access is rarely required since all user-relevant Matrices can
  in principle be accessed via a "-> Global" variable.
3 REF_STRING
  Gives access to a "-> algebra -> variables -> types -> String"
  by the internal reference number.

  Such access is rarely required since all user-relevant Strings can
  in principle be accessed via a "-> Global" variable.
3 REVERSE
  Returns a "-> algebra -> variables -> types -> Matrix" of the same
  size and shape as the Matrix given on input, but with the elements
  in reverse order.

  Example:
!W
  Global evec = 10000 & 15000 & 25000 & 50000
  For e "-> Do -> In" reverse(evec) Do
     Say {e}
  Enddo
!W

  In this example, a vector EVEC is filled with 4 elements. The loop
  over this vector starts from the last element.
3 RMS
  Returns the RMS of an "-> algebra -> variables -> types -> Histogram"
  or a "-> algebra -> variables -> types -> Matrix".

  Using this function with an Histogram is equivalent to calling the
  "-> Call -> INQUIRE_HISTOGRAM" procedure and using its
  "-> Call -> INQUIRE_HISTOGRAM -> rms" argument.

  This function accepts Matrices with any number of dimensions.

  The RMS is for both Histograms and Matrices defined as:
!W
         \Σ(x\²) - \Σ\²(x)/n
  RMS\² = ---------------
               n
!W


  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number". 

  Example:
!W
  Call "-> Call -> book_histogram"(a,100)
  Call "-> Call -> book_matrix"(b,10000)
  For i From 1 To 10000 Do
     Global entry="-> algebra -> functions -> rnd_gauss"
     Call "-> Call -> fill_histogram"(a,entry)
     Global b[i]=entry
  Enddo
  Say "Histogram mean: {"-> algebra -> functions -> mean"(a)}, rms: {rms(a)}"
  Say "Matrix mean: {"-> algebra -> functions -> mean"(b)}, rms: {rms(b)}"
!W


  A test to verify that the mean and RMS for matrices and
  histograms coincide. This should be numerically  exact since
  the mean and RMS for histograms are computed from the entries,
  not from the bin contents.
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 
  "-> algebra -> variables -> types -> Number" but may also be
  of type "-> algebra -> variables -> types -> Histogram" and
  "-> algebra -> variables -> types -> 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.
3 RND_FUNCTION
  Generates random number according to the function that has,
  on beforehand, been specified with a call to
  "-> Call -> PREPARE_RND_FUNCTION".

  A random number sequences according to only one function can
  be generated at the time.

  This generator has no arguments.
3 RND_GAUSS
  Returns a random "-> algebra -> variables -> types -> Number"
  according to a normal distribution, i.e. a Gaussian distribution
  with mean\ =\ 0 and \σ\ =\ 1.

  This function has no arguments.
3 RND_GAMMA
  Returns a random "-> algebra -> variables -> types -> Number" according
  to a \Γ-distribution with the shape parameter p supplied as argument.
  The parameter p has to be\ >\ 0 but does not have to be integer.
!W
  \Γ(x,p) = x\p-1\ e\-x\ / (p-1)!
!W

  Three special cases deserve to be mentioned:
!Wul_start
  - When p=1, the distribution reduces to an exponential, and it is
    then more efficient to use "-> algebra -> functions -> RND_EXPONENTIAL".
  - The Polya distribution, which can be generated using
    "-> algebra -> functions -> RND_POLYA" is in fact a \Γ-distribution,
    with shape parameter p being equal to the mean-1.
  - Also the \χ\²-distribution is a \Γ-distribution, with the shape parameter
    set to p=ndf/2 where ndf is the number of degrees of freedom.
!Wul_end
!D1
  This procedure calls the CERN library routine RNGAMA.
!WThis procedure calls the CERN library routine
!WRNGAMA.

  The shape parameter p is usually specified as a
  "-> algebra -> variables -> types -> Number" but may also be
  of type "-> algebra -> variables -> types -> Histogram" and
  "-> algebra -> variables -> types -> Matrix". In the latter
  two cases, variables of the same type will be returned, taking
  for each output element as shape parameter the corresponding element of
  the argument.

  Example:
!W
  Call "-> Call -> book_histogram"(hrnd,100,0,5)
  For i From 1 To 100000 Do
     Call "-> Call -> fill_histogram"(hrnd,rnd_gamma(2))
  Enddo
  Call "-> Call -> plot_histogram"(hrnd)
  Call "-> Call -> plot_end"
!W

3 RND_LANDAU
  Returns a random "-> algebra -> variables -> types -> Number"
  according to a Landau distribution.

  This function has no arguments.

  A companion random number generator, "-> Call -> RND_VAVILOV",
  is available as a procedure call. This generator is to be used
  when typical single-interaction energy losses are small compared
  with the kinematic maximum energy loss.
3 RND_LAPLACE
  Returns a random "-> algebra -> variables -> types -> Number"
  according to a Laplace distribution:
!W
  P = exp(-x/w)/(2w) for x>0
      exp(+x/w)/(2w) for x<0
!W


  The optional argument w acts as a multiplicative scaling.

  Example:
!W
  Call book_histogram(hl,100,-8,8)
  For i From 1 To 100000 Do
     Call fill_histogram(hl,rnd_laplace(1))
  Enddo
  Call plot_histogram(hl,`x`,`Laplace distribution`)
  Call plot_end
!W

  Which should produce this plot:
!W

3 RND_HISTOGRAM
  Generates random number according to the
  "-> algebra -> variables -> types -> Histogram"
  given as argument.

  Separate random number sequences according to different
  histograms can be generated concurrently.

  The procedure works by creating a cumulative histogram
  and reverse-interpolating it for a uniformly distributed
  random number. Failures can occur for the following reasons:
!Wul_start
  - the histogram contains one or more holes;
  - the data is concentrated in very few bins;
  - a significant fraction of the data is in under- or overflow.
!Wul_end
  If a failure occurs, up to 9 further attempts are made with new
  uniformly distributed random numbers. If the failure persists, the
  global variable "-> algebra -> variables -> predefined -> OK" is
  set to False. Otherwise, it is set to True.

  The argument is mandatory.

  Example:
!W
  // Generate an electron energy spectrum.
  "-> &GAS -> magboltz" xenon 90 co2 10 e-field 250 coll 1 "-> &GAS -> MAGBOLTZ -> keep"

  // This results in a set of arrays, E_1 and F_1 in particular.
  // These arrays are typically too long to be used directly as
  // histograms and need therefore to be rebinned.
  Global bin=5
  Call "-> Call -> book_matrix"(he,"-> algebra -> functions -> entier"("-> algebra -> functions -> size"(f_1)/bin))
  Call "-> Call -> book_matrix"(hf,"-> algebra -> functions -> entier"("-> algebra -> functions -> size"(f_1)/bin))
  For i From 1 To "-> algebra -> functions -> size"(hf) Do
     Global he[i]=0
     Global hf[i]=0
     For j From 1 To bin Do
        Global he[i]=he[i]+e_1[bin*(i-1)+j]
        Global hf[i]=hf[i]+f_1[bin*(i-1)+j]
     Enddo
     Global he[i]=he[i]/bin
     Global hf[i]=hf[i]/bin
  Enddo

  // Convert the rebinned array to a histogram
  Call "-> Call -> matrix_to_histogram"(hf, "-> algebra -> functions -> number"(he[1]), "-> algebra -> functions -> number"(he[size(he)]), histf)

  // Book an histogram with identical parameters
  Call "-> Call -> book_histogram"(check, "-> algebra -> functions -> size"(hf), "-> algebra -> functions -> number"(he[1]), "-> algebra -> functions -> number"(he[size(he)]))

  // And generate 10000 samples
  For i From 1 To 10000 Do
     Call "-> Call -> fill_histogram"(check, rnd_histogram(histf))
  Enddo
  Global check = check * "-> algebra -> functions -> sum"(histf)/"-> algebra -> functions -> sum"(check)

  // Compare
  Call "-> Call -> plot_graph"(he,hf)
  Call "-> Call -> plot_line"(e_1,f_1,`function-2`)
  Call "-> Call -> plot_histogram"(histf, ``,``, `noframe`)
  Call "-> Call -> plot_histogram"(check, ``,``, `noframe`)
  Call "-> Call -> plot_end"
!W

3 RND_POISSON
  Generates Poisson distributed random
  "-> algebra -> variables -> types -> Number"s. The Poisson
  distribution gives the probability that "n" events occur
  during an interval in which on average "mean" events occur.
  This is a discrete probability distribution:
!W
           -mean      n
          e       mean
  P(n) =  -------------
              n!
!W


  The optional argument of this generator specifies the mean of
  the distribution to be generated. If the argument is omitted,
  a mean of 1 is assumed.

!D1
  This procedure calls the CERN library routine RNPSSN.
!WThis procedure calls the CERN library routine
!WRNPSSN.

  The mean is usually specified as a 
  "-> algebra -> variables -> types -> Number" but may also be
  of type "-> algebra -> variables -> types -> Histogram" and
  "-> algebra -> variables -> types -> 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.

  Example:
!W
  Global mean=4.2
  Global nrndm=10000

  Call "-> Call -> book_histogram"(p,20,-0.5,19.5)
  For i From 1 To nrndm Do
     Call "-> Call -> fill_histogram"(p,rnd_poisson(mean))
  Enddo

  Global mu="-> algebra -> functions -> mean"(p)
  Global scale="-> algebra -> functions -> sum"(p)

  Call fit_function(p,`scale*"-> algebra -> functions -> exp"(-mu)*mu^x/"-> algebra -> functions -> gamma"(x+1)`, ...
     mu,scale,emu,escale,`plot,print`)

  Say "Fitted mean: {mu} +/- {emu}, Histogram mean: {mean}, True: {mean}"
  Say "Contents: {scale} +/- {escale}, True: {nrndm}"
!W


  After having filled an histogram (note the binning) with Poisson
  random numbers, we wish to verify the generator. This we do by 
  computing the "-> algebra -> functions -> MEAN" and we also do
  a fit using "-> Call -> FIT_FUNCTION". For the initial guess of the
  parameters we use the mean and the "-> algebra -> functions -> SUM".

  This example only works for small values of the mean since the
  "-> algebra -> functions -> GAMMA" function does not accept large
  arguments. To make it work for larger means, one uses the
  "-> algebra -> functions -> LOG_GAMMA" function:
!W
  "-> Global" mean=50
  Global nrndm=10000

  Call "-> Call -> book_histogram"(p,100,-0.5,99.5)
  For i From 1 To nrndm Do
     Call "-> Call -> fill_histogram"(p,rnd_poisson(mean))
  Enddo

  Global mu="-> algebra -> functions -> mean"(p)
  Global scale="-> algebra -> functions -> sum"(p)

  Call fit_function(p,`scale*"-> algebra -> functions -> exp"(x*"-> algebra -> functions -> log"(mu)-"-> algebra -> functions -> log_gamma"(x+1)-mu)`, ...
     mu,scale,emu,escale,`plot,print`)

  Say "Fitted mean: {mu} +/- {emu}, Histogram mean: {mean}, True: {mean}"
  Say "Contents: {scale} +/- {escale}, True: {nrndm}"
!W

3 RND_POLYA
  Generates Polya distributed random numbers. A Polya distribution
  with parameter \θ is in fact a \Γ-distribution with
  parameter \θ+1. (See "-> algebra -> functions -> RND_GAMMA".)
  For \θ equal to 0, the Polya distribution
  reduces to the exponential distribution.

  The argument specifies the \θ parameter of the distribution
  to be generated. If the argument is omitted, a \θ of 1 is
  assumed.

!D1
  This procedure calls the CERN library routine RNGAMA.
!WThis procedure calls the CERN library routine
!WRNGAMA.

  The \θ parameter is usually specified as a
  "-> algebra -> variables -> types -> Number" but may also be
  of type "-> algebra -> variables -> types -> Histogram" and
  "-> algebra -> variables -> types -> Matrix". In the latter
  two cases, variables of the same type will be returned, taking
  for each output element as \θ the corresponding element of
  the argument.
3 RND_UNIFORM
  Returns a uniformly distributed random
  "-> algebra -> variables -> types -> Number" in the range <0, 1>,
  end-points excluded, scaled with the optional argument.

!D1
  This procedure calls the CERN library routine RANLUX.
!WThis procedure calls the CERN library routine
!WRANLUX.

  The scaling factor is usually specified as a 
  "-> algebra -> variables -> types -> Number" but may also be
  of type "-> algebra -> variables -> types -> Histogram" and
  "-> algebra -> variables -> types -> 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.

  The description of the "-> Call -> FIT_GAUSSIAN" procedure
  shows an example of the use of RND_UNIFORM.

  [The default scaling factor is 1.]
3 ROW
  Returns a 1-dimensional
  "-> algebra -> variables -> types -> Matrix"
  filled with the numbers 1 to n, where n is the argument.
  The argument n is mandatory and should be of type
  "-> algebra -> variables -> types -> Number".

  Use the "-> algebra -> functions -> ZEROES" and
  "-> algebra -> functions -> ONES" functions if you
  wish to create a vector that contains only 0 or only 1.

  Examples:
!W
  "-> Global" xmin=2
  Global xmax=23
  Global nx=200
  Global xlin=xmin+(xmax-xmin)*(row(nx)-1)/(nx-1)
  Global xlog=xmin*(xmax-xmin)^((row(nx)-1)/(nx-1))
!W


  This generates series of nx equally and logarithmically spaced
  points between xmin and xmax.
3 SIN
  Returns the sine of an angle expressed in radians.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 SINH
  Returns the hyperbolic sine of its argument.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 SIZE
  Returns the total "-> algebra -> variables -> types -> Number" of
  elements contains in the "-> algebra -> variables -> types -> Matrix"
  that is given as argument.

  Use the "-> Call -> DIMENSIONS" procedure to obtain more
  detailed information about the structure of the matrix.

  This function is of use if you need to loop over the elements of a
  1-dimensional matrix in order to apply an operation which is not
  available via the operators and procedure calls, e.g.:
!W
  For i From 1 To size(a) "-> Do"
     If a[i]>0 Then
        "-> Global" i0=i
        "-> Do -> Leave"
     Endif
  Enddo
!W


  This finds the first strictly positive element in a matrix.
3 SQRT
  Returns the square root of the argument.

  The argument, or each element of the argument, should be
  equal to or larger than 0.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 STRING
  Converts a variable of any type to a variable of type
  "-> algebra -> variables -> types -> String" as follows:

!Wul_start
  - an "-> algebra -> variables -> types -> Undefined" value
    is converted to the string `Undefined`;
  - a "-> algebra -> variables -> types -> Number" is converted
    to a string that contains the value, formatted in a more or
    less readable form;
  - a "-> algebra -> variables -> types -> Logical" becomes
    either the string `True` or the string `False`;
  - a "-> algebra -> variables -> types -> String" remains
    unchanged;
  - a "-> algebra -> variables -> types -> Matrix" of 1 dimension
    becomes a string with the first few elements of the vector,
    Matrices of higher dimensions are converted to the String
    `Matrix`;
  - an "-> algebra -> variables -> types -> Histogram" becomes
    the string `Histogram`.
!Wul_end

  The STRING function is for instance used to create file names
  that depend on parameters of the chamber being studied:
!W
  "-> Global" argon 70
  Global co2 30
  Global gas_file `argon_`/string(argon)/`_CO2_`/string(co2)/`.gas`
  Call "-> Call -> inquire_file"(gas_file,exist)
  If exist Then
     get {gas_file}
  Else
     write {gas_file}
     magboltz argon {argon} co2 {co2}
  Endif
!W

3 SUM
  Returns the sum of all channels of an
  "-> algebra -> variables -> types -> Histogram" or of all
  elements of a
  "-> algebra -> variables -> types -> Matrix".

  The function returns in either case a value of type
  "-> algebra -> variables -> types -> Number". 
3 TAN
  Returns the tangent of an angle expressed in radians.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 TANH
  Returns the hyperbolic tangent of its argument.

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 TRAILING
  Complement of "-> algebra -> functions -> ENTIER".

  This function can take either an 
  "-> algebra -> variables -> types -> Histogram", a
  "-> algebra -> variables -> types -> Matrix" or a
  "-> algebra -> variables -> types -> Number" as argument.
  The function acts bin-by-bin on Histograms and element-by-element
  on Matrices and returns a value of the same type as the argument.
3 TYPE
  Takes an expression as argument and returns, in the form of a
  "-> algebra -> variables -> types -> String", one of the following
  values:
  `"-> algebra -> variables -> types -> String"`,
  `"-> algebra -> variables -> types -> Number"`,
  `"-> algebra -> variables -> types -> Logical"`,
  `"-> algebra -> variables -> types -> Histogram"`,
  `"-> algebra -> variables -> types -> Matrix"` or
  `"-> algebra -> variables -> types -> Undefined"`.

  This function provides a functionality which is similar to the
  "-> Call -> INQUIRE_TYPE" procedure. The main difference is that it
  is permissible to give the INQUIRE_TYPE procedure as first argument
  a variable that does not yet exist while this is not allowed with
  the TYPE function. The reason for this is that the arguments of
  procedures are automatically declared if they do not yet exist,
  while the arguments of functions must be existing variables. If you
  wish to use the TYPE function and are not sure the variable exists,
  then use the "-> algebra -> functions -> GLOBAL" function.

  Examples:
!W
  "-> Global" a `Hello !`
  "-> Say" {"-> algebra -> functions -> type"(a)}
  Say {type("-> algebra -> functions -> global"(`A`))}

  Say {type(global(`does not exist`))}
!W

  
  Both Say statements in the first example will display "String",
  which is the type the variable A gets by executing the Global
  statement.

  The argument of the GLOBAL function in the second example is not
  a valid name for a global variable, GLOBAL will therefore return
  Nill, of type Undefined.
3 ZEROES
  Returns a 1-dimensional
  "-> algebra -> variables -> types -> Matrix"
  which contains n times the number 0, where n is the argument.
  The argument n is mandatory and should be of type
  "-> algebra -> variables -> types -> Number".

  Use the "-> algebra -> functions -> ONES" function to
  create a vector than contains 1 everywhere and the
  "-> algebra -> functions -> ROW" function if you
  wish to create a vector that contains the numbers 1, 2, 3 ...

  Do not confuse this function with the "-> Call -> ZEROES" procedure.
2 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
  "-> algebra -> 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:
!Wol_start
  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
!Wol_end
3 argument
  The instruction to assign a register to a subroutine argument reads:

!Wtable_start
!T+                                    RP         .
  Description                          Codes
  -----------                          -----

  R(j) \→ Arg(k)                  i  8  j  k
!Wtable_end

  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.
3 arithmetic
  Instruction list codes for operators:

  Numerical binary arithmetic:

!Wtable_start
!T+                                    RP         .
  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
!Wtable_end

  Comparisons resulting in a logical, where numeric equality and non-equality are
  tested at a precision of 10\-5\ or 10\-10\ depending
  on the machine precision:

!Wtable_start
!T+                                    RP         .
  Description                          Codes
  -----------                          -----

  R(i) = R(j) \→ R(k)             i 10  j  k
  R(i) \≠ R(j) \→ R(k)         i 11  j  k
  R(i) \< R(j) \→ R(k)         i 12  j  k
  R(i) \≤ R(j) \→ R(k)         i 13  j  k
  R(i) \> R(j) \→ R(k)         i 14  j  k
  R(i) \≥ R(j) \→ R(k)         i 15  j  k
!Wtable_end

  Logical binary arithmetic:

!Wtable_start
!T+                                    RP         .
  Description                          Codes
  -----------                          -----

  R(i) and R(j) \→ R(k)           i 16  j  k
  R(i) or R(j) \→ R(k)            i 17  j  k
!Wtable_end
3 call
  The instruction to call a procedure which has n arguments and
  has the identification code m, reads:

!Wtable_start
!T+                                    RP         .
  Description                          Codes
  -----------                          -----

  Call procedure m with n args    m  9  n  0
!Wtable_end

  The procedures are listed separately, see "-> Call".
3 functions
  Codes for the various intrinsic functions.

  Numerical functions:

!Wtable_start
!T+                                   RP               +                       .
  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     -
  \√ 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
  \Σ R(i) \→ R(j)           13  6  i  j     SUM
  \Π R(i) \→ R(j)              14  6  i  j     PRODUCT
  Landau R(i) \→ R(j)             18  6  i  j     LANDAU
  Minimum of R(i) \→ R(j)         19  6  i  j     MINIMUM
  Maximum of R(i) \→ R(j)         20  6  i  j     MAXIMUM
  Row of 1 to R(i) \→ R(j)        40  6  i  j     ROW
  Mean of R(i) \→ R(j)            41  6  i  j     MEAN
  RMS of R(i) \→ R(j)             42  6  i  j     RMS
  Size of R(i) \→ R(j)            43  6  i  j     SIZE
  Row of R(i) zeroes \→ R(j)      44  6  i  j     ZEROES
  Row of R(i) ones \→ R(j)        45  6  i  j     ONES
  Existence of file R(i) \→ R(j)  46  6  i  j     EXIST
  \Γ R(i) \→ R(j)           47  6  i  j     GAMMA
!Wtable_end

  Logical functions:

!Wtable_start
!T+                                   RP               +                       .
  Description                         Codes            Name
  -----------                         -----            ----
  not R(i) \→ R(j)                10  6  i  j     NOT
!Wtable_end

  Type conversions:

!Wtable_start
!T+                                   RP               +                       .
  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
!Wtable_end

  Random numbers:

!Wtable_start
!T+                                   RP               +                       .
  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, \θ 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
!Wtable_end

  The random number generators 
  "-> algebra -> functions -> RND_EXPONENTIAL" and
  "-> algebra -> functions -> RND_POISSON"
  have the mean of the distribution as argument. The argument
  of "-> algebra -> functions -> RND_POLYA" is the "theta"
  parameter. These arguments are optional, they default to 1.
  They can generate random number sequences of different
  data types.

  "-> algebra -> functions -> RND_HISTOGRAM" takes an
  "-> algebra -> variables -> types -> Histogram"
  as argument and always returns a single random number.
3 goto
  The jump instruction reads:

!Wtable_start
!T+                               RP         .
  Description                     Codes
  -----------                     -----

  If R(i) Goto Ins(R(j))          i  7  j  0
!Wtable_end

  A direct jumps are obtained by setting R(i) to 1 (i.e. i=-1).
  Setting R(i) to 0 (i.e. i=0) is a no-operation code because
  the jump would never occur.

  A value out of range for R(j) (typically 0) is a alternative
  for "-> algebra -> instruction_list -> return". You are
  allowed to modify the value of R(j) during execution.
3 results
  The instruction to assign a register to an output variable reads:

!Wtable_start
!T+                                    RP         .
  Description                          Codes
  -----------                          -----

  R(i) \→ output variable (j)     0  0  i  j
!Wtable_end
3 return
  To return to the calling procedure, to stop procedure execution,
  and to stop program execution, the following instructions can be
  used:

!Wtable_start
!T+                               RP         .
  Description                     Codes
  -----------                     -----

  Return to calling procedure     i -9  0  0
  Stop procedure execution        i -9  1  0
  Stop program execution          i -9  2  0
!Wtable_end

  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.
2 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.
2 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:
!W
  ADD-ENTRY-POINT
!W

2 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:
!W
  CL-ENTRY [entry_reference]
!W


  Examples:
!W
  CL-ENTRY
  CL-ENTRY 5
!W


  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
  "-> algebra -> MEMORY" command, details about an entry point are
  provided by the "-> algebra -> DISPLAY-ENTRY-POINT" command.
2 DELETE
  Deletes instructions from the instruction list.

  Format:
!W
  DELETE [from [to|LAST]]
!W


  Example:
!W
  DEL
  DEL 1 LAST
!W


  (Both examples delete all instructions.)
2 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:
!W
  DISPLAY-ENTRY-POINT [entry_reference]
!W


  Example:
!W
  DISP-ENTRY
!W


  Shows details about your current entry point.
2 EXECUTE
  Executes one or more lines in the instruction list sequentially,
  ignoring "-> algebra -> instruction_list -> goto" statements.
  This instruction is therefore mainly useful for debugging infinite
  loops.

  Format:
!W
  EXECUTE [from [to|LAST]]
!W


  Example:
!W
  EXEC
!W


  (Execute the whole instruction list, skipping branching statements.)
2 EXIT
  Leaves the editor.

  Format:
!W
  EXIT
!W

2 FUNCTION
  Translates the function provided in the argument into an instruction
  list. No need for "-> introduction -> quotes" around the function,
  even if it contains blanks or commata etc.

  Format:
!W
  FUNCTION function
!W


  Example:
!W
  F ARCTAN (EX/EY)
!W

2 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:
!W
  GARBAGE-COLLECT
!W

2 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:
!W
  INSERT before
!W

2 LIST
  Lists (part of) the instruction list in raw format.

  Format:
!W
  LIST [from [to|LAST]]
!W


  Example:
!W
  LIST 5
!W


  (Lists line 5 only.)
2 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
  "-> algebra -> DISPLAY-ENTRY-POINT" instruction.

  This command can be used both in the algebra editor, which is
  entered by typing @ instead of a formula, or as part of regular
  input, provided the command is prefixed by a @ symbol.

  Formats:
!W
  MEMORY
  @ MEMORY
!W

2 OPTIONS
  The local options described below may as usual be mixed with
  the global options, see the top level "-> OPTIONS" command.

  The algebra OPTIONS can be set via a single-line command as shown
  in the example, and also from within the algebra editor which is
  entered by typing @ instead of a formula.

  Format:
!W
  OPTIONS [NO-"-> algebra -> OPTIONS -> SYNTAX-CHECK" | ALGEBRA-SYNTAX-CHECK | ...
           PROCEDURE-SYNTAX-CHECK] ...
          [SIGNAL-EXPONENTIAL-UNDERFLOW | "-> algebra -> OPTIONS -> IGNORE-EXPONENTIAL-UNDERFLOW"]
!W


  Examples:
!W
  &SIGNAL
  // insert avalanche, time resolution and other settings
  Global phi0=10*pi/180
  @opt "-> algebra -> OPTIONS -> ignore-exponential-underflow"
  "-> &SIGNAL -> signal" ion-tail cross-induced noelectron-pulse ...
     ion-angles 20 angular-spread "-> algebra -> functions -> exp"(-((phi/{phi0})^2))
!W


  Avalanches are spread around the wire with a standard
  deviation of 10\°. This would lead to many underflows
  in the calculation and the spread would be rejected as a
  result. This is why the "-> algebra -> OPTIONS -> IGNORE-EXPONENTIAL-UNDERFLOW" option is used.
!W
  OPTION NO-SYNTAX-CHECK DEBUG
!W


  If you are confident you won't make typing errors\ ...
3 SYNTAX-CHECK
  New instructions entered via "-> algebra -> 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 
  "-> algebra -> instruction_list -> return",
  "-> algebra -> instruction_list -> goto",
  "-> algebra -> instruction_list -> argument" and
  "-> algebra -> instruction_list -> 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.
3 IGNORE-EXPONENTIAL-UNDERFLOW
  If the SIGNAL-EXPONENTIAL-UNDERFLOW option is in effect, which is the initial setting,
  exponentials of negative numbers less than -40 are signalled 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-EXPONENTIAL-UNDERFLOW option is used. When IGNORE-EXPONENTIAL-UNDERFLOW
  is in effect, underflows are not counted.

  Note that this option applies only to exponentials evaluated by algebraic expressions,
  not to exponentials computed by regular Garfield commands.

  These options may also be written IGNORE-UNDERFLOW and SIGNAL-UNDERFLOW.

  [By default, exponential underflows are not signalled.]
3 IGNORE-INPUT-UNDERFLOW
  Values part of commands that are smaller in absolute value than 10\-30\
  are by default set equal to 0.

  This does not apply to results of calculations, for which other limits apply,
  as explained for the "-> algebra -> OPTIONS -> IGNORE-EXPONENTIAL-UNDERFLOW" option.

  [By default, underflow on input is ignored.]
2 PRINT
  Prints (part of) the instruction list in a legible format.

  Format:
!W
  PRINT [from [to|LAST]]
!W


  Example:
!W
  PRINT 2 10
!W


  (Prints lines 2 through 10.)
2 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:
!W
  REGISTER array_index value
!W


  Examples:
!W
  REG 5 10
  REG 5
!W


  (First assign the value 10 to R(5), then check the value.)
2 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:
!W
  RESET
!W

2 RESULTS
  Displays the number of results expected by the calling section.

  Format:
!W
  RESULTS
!W

2 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, steps that are not
  executed 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:
!W
  SIMPLIFY
!W

2 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 "-> algebra -> EXECUTE" in that
  "-> algebra -> instruction_list -> goto" is executed. Loops,
  jumps and if's therefore work as usual.

  Format:
!W
  TEST var1 var2 ...
!W


  Example:
!W
  TEST 2 3 6 10
!W


  (Execute the instruction list after substituting 2 for R(1),
  3 for R(2), 6 for R(3) and 10 for R(4).)
2 VARIABLES
  Lists the names of the valid variables.

  Format:
!W
  VARIABLES
!W

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

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

  Format:
!W
  statement // comment
!W


  Examples:
!W
  "-> Global" a=5 // initialise A

  "-> &CELL -> SOLIDS -> box" "-> &CELL -> SOLIDS -> BOX -> centre"        -1.3    1.39   0   ... // Centre of strip 1
      "-> &CELL -> SOLIDS -> BOX -> half-lengths"   0.01   0.65   0.1 ... // Dimensions
      "-> graphics -> REPRESENTATION -> item -> conductors-2"                         // Material
!W

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

  Format:
!W
  * comment
!W


  Example:
!W
  * this is a comment ...
    that spans several ...
    lines
!W

1 control_keys
  Control keys can be used to interrupt the program.
2 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.
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.
2 Unix
  The program can be stopped by typing control-C.

  Lengthy loops can be interrupted by checking for the existence of a
  file. For example, the following loop
!W
  For i From 1 To 10000 Do
     If "-> algebra -> functions -> exist"(`stop_loop`) Then "-> Do -> Leave"
     // Lengthy calculation
  Enddo
!W

  checks each iteration whether a file called "stop_loop" exists and
  ends the loop iteration if this is the case. To stop the loop, the
  user would type (to the Unix command prompt):
!W
  touch stop_loop
!W

  There is currently no elegant built-in 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.
2 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.
1 dataset
  The dataset commands manipulate Garfield datasets.

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

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

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

  All dataset commands start with a % sign. If you have lots of
  dataset commands to do, you may prefer to enter the dataset
  subsection by typing only the % sign, without arguments. In the
  dataset subsection no % has to be prefixed to the commands.
  You may not enter other subsections from within the dataset
  subsection. EXIT will get you back to the section you came from.
2 structure
  A Garfield library has a "-> dataset -> structure -> file" name
  which identifies it to the operating system. The file consists
  internally of a series of "-> dataset -> structure -> member"s.
  A member has a name and a "-> dataset -> structure -> type",
  neither of which needs to be unique, and may optionally also have
  a "-> dataset -> structure -> remark" attached to it for ease of
  identification.
3 file
  The file name of a Garfield library identifies the library to
  the operating system. The name of a Garfield library is normally
  chosen by the user.

  In general, the file name should be entered the way it is usually
  entered on system where you run Garfield. There are however a few
  points to keep in mind:
!Wul_start
  - Some operating systems, such as Unix, distinguish case in the
    file names while Garfield translates all normal commands to upper
    case. Unix file names furthermore sometimes contain symbols that
    act as "-> introduction -> separators" in Garfield (blank, comma,
    colon, equal sign).
    To avoid problems, place double "-> introduction -> quotes" around
    the file name on such systems.
  - You may use environment variables in Unix file names, prefixing them
    with a dollar sign ($). You may also use the tilde (~) to point to
    your the home directory and, in the CERN AFS area, the tilde followed
    by a user name for another user's home directory.
  - File names on Vax/VMS and OpenVMS can contain colons (:) which
    act as separators in Garfield. Here too, you have to place either
    single or double quotes around the file name.
  - 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.
!Wul_end

  When you access a file via a procedure "-> Call", then the file name
  is contained in a "-> algebra -> variables -> types -> String" and
  no further precautions need to be taken.

  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. 
3 member
  Garfield files are plain text files. For Garfield purposes, they are
  composed of one or more members - but the operating system will not
  be aware of this.

  Each member is identified through a name, a string of 8 characters.
  As a rule, the user can chose the member name but users tend to leave
  the field empty (in which case it will be set to "< none >").

  Since the various GET commands will by default search for the
  first member of the appropriate "-> dataset -> structure -> type",
  you can leave the member name blank if the file contains only one
  member of each type.

  New members are appended to a file, they do not replace existing
  members.

  Although a single file is allowed to contain several members with
  the same name and the same type, this is to be avoided since only
  the first of these members can be accessed. Problems of this kind
  occur for instance if you have a dataset that contains histograms
  which are retrieved, updated, and then written back to the file.
  The use of the "-> OPTIONS -> DELETE-OLD-MEMBER" global option is
  recommended in such cases.

  The "-> dataset -> INDEX" dataset command and the
  "-> Call -> INQUIRE_MEMBER" procedure can be used to find out
  which members are present in a dataset. The dataset command
  "-> dataset -> DELETE" will mark members for deletion and
  "-> dataset -> PURGE" will remove deleted members from a dataset.

  Case is not relevant in member names. If, when writing, you surround
  the member name with double "-> introduction -> quotes", then the
  member will have the exact name that you entered. However, when 
  reading, all case variations will be declared to match. For instance,
  a member called "ExB" in the file can be retrieved as "exb", "eXb",
  "EXB" etc.

  Each member starts with a header record formatted as follows: 

!Wtable_start
!T+           +                                                   R     .
  ----------------------------------------------------------------------
  Character   Contents                                            Length
  ----------------------------------------------------------------------
  1           a percent sign (%)                                       1
  2           a blank, changed to 'X' if the member is deleted         1
  3-10        the string "Created "                                    8
  11-18       day (dd/mm/yy) on which the member was written           8
  19-22       the string " at "                                        4
  23-30       time (hh.mm.ss) at which the member was written          8
  31          is blank                                                 1
  32-39       member name                                              8
  40          is blank                                                 1
  41-48       type of the member                                       8
  49          is blank                                                 1
  50          double quote (")                                         1
  51-79       remark                                                  29
  80          double quote (")                                         1
  ----------------------------------------------------------------------
!Wtable_end
3 type
  The type 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.

  The type given to a member is chosen by the program according
  to the following scheme:

!Wtable_start
!T+          +                                      +        .
  -----------------------------------------------------------
  Type       Description                            Main user
  -----------------------------------------------------------
  ARRIVAL    Output of the ARRIVAL instruction      User
  CELL       Compact format cell description        Internal
  ISOCHRON   Equal time contours (isochrons)        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
  -----------------------------------------------------------
!Wtable_end

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

  The remark has a length of 1 to 29 characters.
2 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:
!W
  % DEFAULT file_specification
!W


  Examples:
!W
  % DEF
  % DEF 'VAXODIE::'
  %default .GARFLIB
!W


  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 "-> introduction -> quotes", the colons are
  "-> introduction -> separators" and would be discarded without
  the quotes). The last example ensures that the libraries to be
  read and written have extension GARFLIB.
2 DELETE
  Marks a "-> dataset -> structure -> member" in a dataset for removal.
  This makes the member invisible for commands like GET, but does not
  remove the member from the "-> dataset -> structure -> file".

  Removing members physically from a dataset is done by
  "-> dataset -> PURGE" . "-> dataset -> RECOVER" will undo a %DELETE. 

  Both the member and the "-> dataset -> structure -> type" may be
  wildcards (a * matches every string).

  Format:
!W
  %DELETE file member [type]
!W

2 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 !
2 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:
!W
  EXIT
!W

2 INDEX
  Produces a directory listing of "-> dataset -> structure -> member"s
  in a "-> dataset -> structure -> file".

  The member and "-> dataset -> structure -> type", if you enter 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 "-> Call -> INQUIRE_MEMBER" procedure can be used to
  determine whether a member exists in a dataset.

  Format:
!W
  %INDEX file [member] [type]
!W

2 LIST
  Displays the contents of one or more "-> dataset -> structure -> member"s
  contained in a Garfield "-> dataset -> structure -> file". You may
  optionally request listing of only one "-> dataset -> structure -> type"
  of member. 

  One can re-rout the "-> output" of this command to a file.

  Both the member and the type may be of the wildcard type (a * matches
  any string).

  Format:
!W
  %LIST file [member] [type]
!W

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

!Wdl_start
!T+                    +
  -----------------------------------------------------------------
  System               File name
  -----------------------------------------------------------------
  CMS                  GARFIELD RAWHELP
  Apollo, Cray, Sun    help_raw$garfield
  Vax                  GARFIELD.HLP (accessed as HELP_RAW$GARFIELD)
  -----------------------------------------------------------------
!Wdl_end

  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.
2 PURGE
  This instruction removes deleted members from a
  "-> dataset -> structure -> file". No recovery is possible,
  unless you made a backup yourself.

  Member and type are not specified on this command.

  Format:
!W
  %PURGE file
!W

2 RECOVER
  Recovers deleted "-> dataset -> structure -> member"s from a
  "-> dataset -> structure -> file" that has not yet been purged.

  Both the member and the "-> dataset -> structure -> type" may be
  wildcards (a * matches every string).

  Format:
!W
  %RECOVER file member [type]
!W

1 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:
!W
  ERROR-HANDLING MESSAGE mess-id ...
                 [PRINT {ALWAYS | NEVER | nprint}] ...
                 [ABEND {NEVER | nabend}]
!W

  
  mess-id Is the identifier of the message as listed in the 'green
  book' of CERN program library writeups. Both nprint and nabend
  are meaningful only in the range 0 to 100. Execution is terminated
  at the nabend+1 occurrence of the error.

  For further details, see short writeup N001:
  http://consult.cern.ch/shortwrups/n001/top.html
1 graphics
  Most of the graphics settings can be changed during the run.
  For instance, one can:

!Wul_start
  - add, open and activate workstations, 
  - control waiting and screen clearing before and after plots,
  - switch between linear and log scales,
  - add or change colour definitions,
  - change the appearance of elements of the plots.
!Wul_end

  Settings that are common for most of your runs can be placed
  more conveniently in your 
!D2
  initialisation file, examples of which can be found at the URL
  http://cern.ch/garfield/files/#init.
!W
!Winitialisation file.
  This is for instance the case of the colours and the
  representations.

  All graphics commands start with a ! sign. If you have lots of
  graphics things to do, you may prefer to enter the graphics
  subsection by typing only the ! sign, without arguments. In the
  graphics subsection no ! has to be prefixed to the commands.
  You may not enter other subsections from within the graphics
  subsection. EXIT will get you back to the section you came from.
2 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:

!Wul_start
  - render graphics output
  - store graphics output
  - obtain graphics input
!Wul_end

  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.

!D3
  These defaults can be changed both with the command line
  arguments (-terminal and -metafile) and from the running
  program via the commands described below.
!WThese defaults can be changed both with the command line
!Wline arguments
!W-terminal
!Wand
!W-metafile
!Wand 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:

!Wdl_start
!T+          +
  --------------------------------------------------------------
  state      description
  --------------------------------------------------------------
  defined    A workstation in state "defined" does not receive
             graphics output, 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.
  --------------------------------------------------------------
!Wdl_end
  
  Moving between the 3 states is accomplished with the following
  set of commands:

!Wtable_start
!T+          +IP                         +IP                    .
  --------------------------------------------------------------
  state      reached from previous by    to return to previous
  --------------------------------------------------------------
  defined    ADD-WORKSTATION             DELETE-WORKSTATION
  open       OPEN-WORKSTATION            CLOSE-WORKSTATION
  active     ACTIVATE-WORKSTATION        DEACTIVATE-WORKSTATION
  --------------------------------------------------------------
!Wtable_end
2 ACTIVATE-WORKSTATION
  Activates a "-> graphics -> workstation".

  A workstation that is to be activated, must already be "open". If you
  try to activate a workstation that is "defined" but not "open", then
  an implicit !"-> graphics -> OPEN-WORKSTATION" is performed.

  After this operation, the workstation is in the GKS state "active"
  which means that it will receive graphics output. The workstation
  can then be deactivated with !"-> graphics -> DEACTIVATE-WORKSTATION".

  The argument is an alphanumeric string designating the workstation,
  Usually, this will be the name that you gave to the workstation when
  issuing a !"-> graphics -> ADD-WORKSTATION" command, but this can also
  be one of the two workstations that can be predefined: TERMINAL and
  METAFILE. Whether these 2 are defined or not depends on the mode in
  which you run Garfield.

  Format:
!W
  ! ACTIVATE-WORKSTATION workstation
!W


  Example:
!W
  ! deact metafile
  (make some plots)
  ! act metafile
  (make final version of plots again)
!W


  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.
2 ADD-WORKSTATION
  Is used to create additional "-> graphics -> workstation"s.

  Up to two workstations can be predefined in Garfield: TERMINAL and/or
  METAFILE. You can manipulate them like any other workstation.

  After !ADD-WORKSTATION, the workstation is in the state 'defined',
  which in GKS terminology means that the workstation is neither 'open'
  nor 'active'. Thus, the workstation will not receive any graphics
  output until you have used !"-> graphics -> OPEN-WORKSTATION" and
  !"-> graphics -> ACTIVATE-WORKSTATION" to first open and then
  activate the newly defined workstation.

  A workstation displays can as a rule handle both input and output,
  and the output that is sent there will as a rule not be stored.
  The first format below deals with this situation.

  Output-only workstations, second format, are associated with a graphics
  file which will store the images. By default, it is assumed that one
  file can contain any number of images. Use the
  "-> graphics -> ADD-WORKSTATION -> SINGLE-FRAME-FILE"
  option in case the output format you wish to use can only deal with
  a single image per file.

  In both formats, either the type (e.g. "inquire" for X-windows inquiry
  at startup, or "EPS" for Encapsulated PostScript ) or the GKS identifier
  (the driver number) must be specified, but not both.

  Format for input/output workstations:
!W
  ! ADD-WORKSTATION name [TYPE  "-> graphics -> ADD-WORKSTATION -> type"  |  GKS-IDENTIFIER  "-> graphics -> ADD-WORKSTATION -> identifier"] ...
                         [CONNECTION-IDENTIFIER  "-> graphics -> ADD-WORKSTATION -> connection"]
!W


  Format for output (metafile, PostScript etc) workstations:
!W
  ! ADD-WORKSTATION name [TYPE  "-> graphics -> ADD-WORKSTATION -> type"  |  GKS-IDENTIFIER  "-> graphics -> ADD-WORKSTATION -> identifier"] ...
                         FILE-NAME  "-> graphics -> ADD-WORKSTATION -> file" ...
                         [OFFSET  "-> graphics -> ADD-WORKSTATION -> offset"] ...
                         ["-> graphics -> ADD-WORKSTATION -> MULTIPLE-FRAME-FILE" | "-> graphics -> ADD-WORKSTATION -> SINGLE-FRAME-FILE"]
!W


  Examples:
!W
  !add postscript type ps file-name garfield.ps
!W


  This instruction adds a PostScript formatted metafile.
!W
  Global quencher `CH4`
  Global ps True
  If ps Then
     !add meta type PostScript file-name "gain_{quencher}.ps"
     !open meta
     !act meta
  Endif

  ...

  If ps Then
      !deact meta
      !close meta
      !del meta
  Endif
!W


  The name of the PostScript file is made to depend on the
  quencher gas which is used. Note the use of 
  "-> algebra -> variables -> substitution" using curly
  brackets.
3 name
  The name of the workstation you wish to create.

  This should be a character string of 20 characters or less.

  [No default, this is a mandatory argument.]
3 type
  States the type of workstation you wish to open. The list of known types
  varies with the graphics system you are using.

  You've to specify either a type or a GKS 
  "-> graphics -> ADD-WORKSTATION -> identifier", but not both.
4 GTS-GRAL
  On Apollo:

!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  DN300_bw                      10002         1  in/out Apollo DN300
  DN3000_bw                     10002         1  in/out Apollo DN3000 B/W
  DN3000_colour                 10004         1  in/out Apollo DN3000 colour
  DN550_colour                  10003         1  in/out Apollo DN550 B/W
  DN660_colour                  10003         1  in/out Apollo DN660 B/W
  GSR_1                          9701         1  in/out -
  GSR_2                          9702         1  in/out -
  GSR_3                          9703         1  in/out -
  GSR_4                          9704         1  in/out -
  GSR_5                          9705         1  in/out -
  GSR_6                          9706         1  in/out -
  GSR_7                          9707         1  in/out -
  GSR_8                          9708         1  in/out -
  X_windows_0                   32120         1  in/out X windows screen 0
  X_windows_1                   32121         1  in/out X windows screen 1
  X_windows_2                   32122         1  in/out X windows screen 2
  X_windows_3                   32123         1  in/out X windows screen 3
  X_windows_4                   32124         1  in/out X windows screen 4
  X_windows_5                   32125         1  in/out X windows screen 5
  X_windows_6                   32126         1  in/out X windows screen 6
  X_windows_7                   32127         1  in/out X windows screen 7
  X_windows_8                   32128         1  in/out X windows screen 8
  X_windows_9                   32129         1  in/out X windows screen 9
  X_windows                     32120         1  in/out X windows
  APPENDIX_E                        4         0  output Appendix E metafile
  PS_portrait_colour            12201       100  output PostScript metafile
  PS_landscape_colour           12202       100  output PostScript metafile
  PS_landscape_bw               12204       100  output PostScript metafile
  PS_portrait_bw                12203       100  output PostScript metafile
  PostScript                    12203       100  output PostScript metafile
  EPS_portrait_colour           12201       200  output Encapsulated PostScript
  EPS_landscape_colour          12202       200  output Encapsulated PostScript
  EPS_landscape_bw              12204       200  output Encapsulated PostScript
  EPS_portrait_bw               12203       200  output Encapsulated PostScript
  Encapsulated_PS               12203       200  output Encapsulated PostScript
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: DN3000_bw.
  Batch default: PS_portrait_bw.

  Other than Apollo:

!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  VT100_RETROGRAPHICS            1001         1  in/out Digital
  VT100_SELENAR                  1002         1  in/out Digital
  VT125_REGIS                    1010         1  in/out Digital
  VT240_REGIS                    1020         1  in/out Digital
  VT241_REGIS                    1021         1  in/out Digital
  VT340                          1030         1  in/out Digital
  VAXSTATION                     8601         1  in/out Digital
  PG7800                         7878         1  in/out Pericom
  MG600                          7800         1  in/out Pericom
  MX2000                          221         1  in/out Pericom
  MX7000                          221         1  in/out Pericom
  MX8000                          227         1  in/out Pericom
  4010                            101         1  in/out Tektronix
  4012                            102         1  in/out Tektronix
  4014                            101         1  in/out Tektronix
  4015                            103         1  in/out Tektronix
  4105                            110         1  in/out Tektronix
  4107                            121         1  in/out Tektronix
  4109                            122         1  in/out Tektronix
  4207                            121         1  in/out Tektronix
  4209                            122         1  in/out Tektronix
  4111                            123         1  in/out Tektronix
  4113                            125         1  in/out Tektronix
  4114                            127         1  in/out Tektronix
  4115                            127         1  in/out Tektronix
  FALCO                           114         1  in/out Falco
  X_WINDOWS_0                   32120         1  in/out X-windows screen 0
  X_WINDOWS_1                   32121         1  in/out X-windows screen 1
  X_WINDOWS_2                   32122         1  in/out X-windows screen 2
  X_WINDOWS_3                   32123         1  in/out X-windows screen 3
  X_WINDOWS_4                   32124         1  in/out X-windows screen 4
  X_WINDOWS_5                   32125         1  in/out X-windows screen 5
  X_WINDOWS_6                   32126         1  in/out X-windows screen 6
  X_WINDOWS_7                   32127         1  in/out X-windows screen 7
  X_WINDOWS_8                   32128         1  in/out X-windows screen 8
  X_WINDOWS_9                   32129         1  in/out X-windows screen 9
  X_WINDOWS                     32120         1  in/out X-windows
  PT-100G                         112         1  in/out -
  APPENDIX_E                        4         0  output Appendix E metafile
  PS_PORTRAIT_COLOUR            12201       100  output PostScript metafile
  PS_LANDSCAPE_COLOUR           12202       100  output PostScript metafile
  PS_LANDSCAPE_BW               12204       100  output PostScript metafile
  PS_PORTRAIT_BW                12203       100  output PostScript metafile
  POSTSCRIPT                    12203       100  output PostScript metafile
  EPS_PORTRAIT_COLOUR           12201       200  output Encapsulated PostScript
  EPS_LANDSCAPE_COLOUR          12202       200  output Encapsulated PostScript
  EPS_LANDSCAPE_BW              12204       200  output Encapsulated PostScript
  EPS_PORTRAIT_BW               12203       200  output Encapsulated PostScript
  ENCAPSULATED_PS               12203       200  output Encapsulated PostScript
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive_default: PG7800
  Batch_default: APPENDIX_E
4 Dec-GKS
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  LOGICAL                           0         0  in/out defined by a logical
  VT125_COLOUR                     11         0  in/out Digital
  VT125_BW                         12         0  in/out Digital
  VT240_COLOUR                     13         0  in/out Digital
  VT240_BW                         14         0  in/out Digital
  VT330                            16         0  in/out Digital
  VT340                            17         0  in/out Digital
  VAXSTATION_1                     42         0  in/out Digital
  VAXSTATION_2                     41         0  in/out Digital
  VS_1                             42         0  in/out Digital
  VS_2                             41         0  in/out Digital
  VS_2000                          41         0  in/out Digital
  DECWINDOWS                      211         0  in/out Digital
  4014                             72         0  in/out Tektronix
  4017                             82         0  in/out Tektronix
  POSTSCRIPT                       61         0  output PostScript metafile
  PS                               61         0  output PostScript metafile
  METAFILE                          2         0  output Appendix E metafile
  DECGKS_MO                         2         0  output Metafile output
  CGM                               7         0  output Computer graphics metafile
  LCP01                            15         0  output -
  LCG01                            15         0  output -
  LN03                             38         0  output -
  HP7475                           51         0  output Hewlett-Packard
  HP7550                           53         0  output Hewlett-Packard
  HP7580                           54         0  output Hewlett-Packard
  HP7585                           56         0  output Hewlett-Packard
  LBP8A2                          531         0  output Canon
  L880                            532         0  output Kyocera
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: 4014
  Batch default: POSTSCRIPT
4 Plot-10-GKS
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  4014_NOTABLET                401400        -2  in/out Tektronix
  4014_TABLET                  401401        -2  in/out Tektronix
  4105                         410500        -2  in/out Tektronix
  4107                         410700        -2  in/out Tektronix
  4109                         410900        -2  in/out Tektronix
  PERICOM                      301400        -2  in/out Pericom
  PLOT10_MO                    100000         0  output Metafile output
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: PERICOM
  Batch default : PLOT10_MO
4 mGKS
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  borrow                       300009         1  in/out -
  frame                        300010         1  in/out -
  direct                       300011         1  in/out -
  4014                         401400         1  in/out Tektronix
  PERICOM                      301400         1  in/out Pericom
  APPENDIX_E                   300018         0  output Appendix E metafile
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: PERICOM.
  Batch default: APPENDIX_E.
4 Sun-GKS
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  Console                           4         1  in/out Workstation console
  Appendix_E                        7         0  output Appendix E metafile
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive_default: Console.
  Batch_default: Appendix_E.
4 GKS-COMPATIBILITY
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  Console                           1         1  in/out Workstation console
  X_windows                         6        -1  in/out X windows
  GDF                               5         0  output -
  MO                                3         0  output Metafile output
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: X_windows
  Batch default: MO
4 ATC-GKS
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  VT125_REGIS                    2600         1  in/out Digital
  VT240_REGIS                    2601         1  in/out Digital
  VT241_REGIS                    2602         1  in/out Digital
  VT330                          2603         1  in/out Digital
  VT340                          2604         1  in/out Digital
  VT340_COLOUR                   2505         1  in/out Digital
  4010                           2500         1  in/out Tektronix
  COMP_4010                      2501         1  in/out Tektronix
  4014                           2400         1  in/out Tektronix
  4105                           2300         1  in/out Tektronix
  PIX_4105                       2301         1  in/out Tektronix
  COMP_4105                      2302         1  in/out Tektronix
  4107                           3100         1  in/out Tektronix
  12B_4107                       3101         1  in/out Tektronix
  4205                           3102         1  in/out Tektronix
  12B_4205                       3103         1  in/out Tektronix
  4208                           3104         1  in/out Tektronix
  12B_4208                       3105         1  in/out Tektronix
  4111                           3200         1  in/out Tektronix
  32B_4111                       3201         1  in/out Tektronix
  4115                           3202         1  in/out Tektronix
  32B_4115                       3203         1  in/out Tektronix
  4125                           3204         1  in/out Tektronix
  32B_4125                       3205         1  in/out Tektronix
  CIT_414A                       2502         1  in/out C-ITOH 414A
  GRAPHON                        2506         1  in/out Graphon 140, 230
  LAND_IMG                       6300         1  in/out Imagen landscape
  PORT_IMG                       6301         1  in/out Imagen portrait
  RETRO                          3203         1  in/out Retrographics VT640
  X11                            5300         1  in/out X windows
  X_WINDOWS                      5300         1  in/out X windows
  BS_X11                         5350         1  in/out X11 (back and store)
  CGM_BIN                       10100       100  output Computer graphics metafile
  CGM_MBIN                      10101       100  output Computer graphics metafile
  CGM_CHAR                      10110       200  output Computer graphics metafile
  CGM_TEXT                      10120       300  output Computer graphics metafile
  CGM_LBIN                      10150       100  output Computer graphics metafile
  CGM_LCHAR                     10160       200  output Computer graphics metafile
  CGM_LTEXT                     10170       300  output Computer graphics metafile
  PS_PORTRAIT_COLOUR             1900       400  output PostScript
  PS_LANDSCAPE_COLOUR            1901       400  output PostScript
  PS_LANDSCAPE_BW                1901       400  output PostScript
  PS_PORTRAIT_BW                 1900       400  output PostScript
  POSTSCRIPT                     1900       400  output PostScript
  EPS_PORTRAIT_COLOUR            1900       400  output Encapsulated PostScript
  EPS_LANDSCAPE_COLOUR           1901       400  output Encapsulated PostScript
  EPS_LANDSCAPE_BW               1901       400  output Encapsulated PostScript
  EPS_PORTRAIT_BW                1900       400  output Encapsulated PostScript
  ENCAPSULATED_PS                1900       400  output Encapsulated PostScript
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: VT241_REGIS
  Batch_default: PS_PORTRAIT_COLOUR
4 HIGZ
!Wtable_start
!T+                    R                 R      R       +                         .
  --------------------------------------------------------------------------------
  Type                 GKS identifier    Offset   Class Description
  --------------------------------------------------------------------------------
  0                                 0         0       - No terminal output
  NONE                              0         0       - No terminal output
  none                              0         0       - No terminal output
  INQUIRE                          -1         0 unknown Inquire at startup
  inquire                          -1         0 unknown Inquire at startup
  1                                 1         0  in/out HIGZ window 1
  2                                 2         0  in/out HIGZ window 1
  3                                 3         0  in/out HIGZ window 1
  4                                 4         0  in/out HIGZ window 1
  5                                 5         0  in/out HIGZ window 1
  6                                 6         0  in/out HIGZ window 1
  7                                 7         0  in/out HIGZ window 1
  8                                 8         0  in/out HIGZ window 1
  9                                 9         0  in/out HIGZ window 1
  7878                           7878         0  in/out Falco
  FALCO                          7878         0  in/out Falco
  Falco                          7878         0  in/out Falco
  XTERM                          7879         0  in/out X terminal
  PS_LANDSCAPE                   -112         0  output PostScript
  PS_landscape                   -112         0  output PostScript
  PS_PORTRAIT                    -111         0  output PostScript
  PS_portrait                    -111         0  output PostScript
  POSTSCRIPT                     -111         0  output PostScript
  PostScript                     -111         0  output PostScript
  EPS                            -113         0  output Encapsulated PostScript
  ENCAPSULATED_PS                -113         0  output Encapsulated PostScript
  encapsulated_PS                -113         0  output Encapsulated PostScript
  ENCAPSULATED_POSTSCR           -113         0  output Encapsulated PostScript
  encapsulated_PostScr           -113         0  output Encapsulated PostScript
  LATEX                          -777         0  output LaTeX
  LaTeX                          -777         0  output LaTeX
  --------------------------------------------------------------------------------
!Wtable_end

  Interactive default: inquire.
  Batch default: PostScript.
3 identifier
  The GKS identifier of the workstation you are defining.
  This number is found in the documentation of your GKS system.

  You've to specify either a "-> graphics -> ADD-WORKSTATION -> type"
  or a GKS identifier, but not both.
3 connection
  The connection identifier for workstations not associated with a file.
  The way the connection identifier is to be chosen should be described
  in the GKS documentation.

  Workstations associated with a file are connected via a logical unit
  which is chosen by Garfield, and the connection identifier is in this
  case given by the logical unit number plus an 
  "-> graphics -> ADD-WORKSTATION -> offset".

  [This parameter is optional and defaults to 1.]
3 offset
  Specifies the offset between logical unit and connection identifier
  for workstations associated with a file.

  This parameter should not be specified when you are adding a 
  workstation that is not associated with a file.

  This parameter is used by certain GKS systems to distinguish closely
  related workstation types. Details should be contained in the GKS
  documentation.

  [If you describe the workstation by "-> graphics -> ADD-WORKSTATION -> type",
  you do not have to specify the offset. Specifying the parameter is optional
  if you describe the workstation by GKS
  "-> graphics -> ADD-WORKSTATION -> identifier". In the latter case it
  defaults to 0.]
3 file
  The file to be associated with the workstation.

  This file is opened at the time the "-> graphics -> OPEN-WORKSTATION"
  command is issued and it is closed by "-> graphics -> CLOSE-WORKSTATION".

  The file name is allowed to be an expression in terms of "-> Global"
  variables, to be evaluated at the time the workstation is opened.
  This is useful if the
  "-> graphics -> ADD-WORKSTATION -> SINGLE-FRAME-FILE" option is specified.

  [This parameter is mandatory for workstations which are output-only.]
3 MULTIPLE-FRAME-FILE
  Workstations such as terminal screens and PostScript files are designed
  to receive several frames one after the other. For such workstations,
  the option MULTIPLE-FRAME-FILE should be specified.

  [This option is default except if the file name contains curly brackets.]
3 SINGLE-FRAME-FILE
  Workstations such as Encapsulated PostScript files can only store
  a single frame. A new file should be opened for the next frame. This
  is done when the option SINGLE-FRAME-FILE is specified. 

  This option is default if the file name associated with the workstation
  is constructed such that it depends on "-> Global" variables, as in the
  following example:
!W
!D1
  !add epsfig type EPS file-name "fig\{frame\}.eps"
!R!add epsfig type EPS file-name "fig\\{frame\\}.eps"
!W


  Here, the file name depends on the "-> algebra -> variables -> predefined"
  variable "-> algebra -> variables -> predefined -> FRAME" which is
  automatically incremented for each new frame, but any expression in terms
  of global variables can be used.

  Note the use of the "-> translation -> ESCAPE" character (a backslash in
  this example): without backslash, the expression would be substituted
  using the value of FRAME at the time the command is issued and subsequent 
  changes in the value of FRAME would not be reflected in the file name.
  With the backslash, the { and } are preserved as part of the string and 
  "-> algebra -> variables -> substitution" of the value of FRAME is done
  only when the file is opened.

  If you select this option and specify a static file name, then the file
  will be overwritten each time a new plot is made.

  [This option is default if the file name contains curly brackets.]
2 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:
!W
  !ARROW-TIP-ANGLE  angle
!W


  Example:
!W
  !arrow-angle 60
!W


  This would make the tip angles twice the default.

  [The default setting is 30\°.]
2 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 either as an absolute length
  in normalised device coordinates (in which the screen has a
  width and height of 1) or as a fraction of the total length
  of the arrow, in the range 0 (excluded) to 1 (included).

  Format:
!W
  !ARROW-TIP-LENGTH length [RELATIVE | ABSOLUTE]
!W


  Example:
!W
  !arrow-length 0.2
!W


  This would make the tip a bit shorter than the default.

  [The default setting is 0.3, relative.]
2 BARCHART-WIDTH
  Determines the width of the bars in bar charts, as plotted
  with "-> Call -> PLOT_BARCHART".

  The width should be specified as a fraction of the maximum
  bin width, in the range 0 (excluded) to 1 (included). The bars
  touch if set to 1, effectively producing an histogram.
  

  Format:
!W
  !BARCHART-WIDTH fraction
!W


  Example:
!W
  !bar-w 0.5
!W


  This would make the bars much more narrow than default.

  [The default setting is 0.9.]
2 CLEAR-SCREEN
  Clears all active workstations.

  Format:
!W
  !CLEAR-SCREEN
!W

2 CLOSE-WORKSTATION
  Closes a "-> graphics -> 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 !"-> graphics -> OPEN-WORKSTATION" and
  then be activated with !"-> graphics -> ACTIVATE-WORKSTATION".

  Any metafile attached to the workstation being closed, will first
  be completed with any data that might still be buffered and then
  the file will be closed. The file will be overwritten if you perform
  an !"-> graphics -> OPEN-WORKSTATION" on the same workstation.

  If !CLOSE-WORKSTATION is invoked for a workstation that is still in
  the state "active", then !"-> graphics -> DEACTIVATE-WORKSTATION"
  will automatically be called before closing the workstation.

  Format:
!W
  ! CLOSE-WORKSTATION workstation
!W


  Example:
!W
  !close metafile
!W


  This will deactivate workstation METAFILE if still active,
  then close the workstation and close the file receiving the
  graphics output.
2 COLOUR
  When using an output device that is capable of rendering colours,
  you may prefer to distinguish the various components of the
  plots by colour rather than by e.g. line type. Examples of such
  settings can be found in the
!D2
  initialisation files, which can be found at the URL
  http://cern.ch/garfield/files/#init,
!W
!Winitialisation files
  for colour displays and for colour transparencies.

  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.

  Use the "-> graphics -> MAP-COLOURS" graphics command to inspect
  graphically the colours which are currently defined.

  Format:
!W
  ! COLOUR colour_name {RED red BLUE blue GREEN green | ...
                        RGB hex}                        ...
                       [WORKSTATION wkid]
!W


  Examples:
!W
  ! COL RED BLUE 0 GREEN 0 RED 1
  ! COL LIGHT_BLUE BLUE 1 RED 0 GREEN 1
!W

3 colour_name
  A character string (of length 20 or less) via which you will
  refer to the colour in "-> graphics -> REPRESENTATION" instructions.

  If the colour has already been defined, then its colour composition
  will be modified. On workstations which permit this, the change will
  be visible in currently displayed graphics that use the colour.

  If the colour has not yet been defined, then it will be added to the
  colour table (provided there is still room).

  The current definition of a colour will be shown if only a colour name
  is specified. All currently defined colours are listed if no arguments
  are given.
3 red
  The fraction of red, on a scale of 0 to 1, inclusive.

  For the FOREGROUND colour, the red fraction is 1,
  for the BACKGROUND colour it is 0.

  [No default, the amount of red must be specified.]
3 green
  The fraction of green, on a scale of 0 to 1, inclusive.

  For the FOREGROUND colour, the green fraction is 1,
  for the BACKGROUND colour it is 0.

  [No default, the amount of green must be specified.]
3 blue
  The fraction of blue, on a scale of 0 to 1, inclusive.

  For the FOREGROUND colour, the blue fraction is 1,
  for the BACKGROUND colour it is 0.

  [No default, the amount of blue must be specified.]
3 hex
  The amounts of red, blue and green in the form of a single hexadecimal number.

  Red would be specified as FF0000, green as 00FF00 and blue as 0000FF.

  [No default, all colour components must be specified.]
3 wkid
  The format allows for a workstation to be specified, but this should
  for the time being not be used.
2 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 \ε
  parameters by a factor of 10.

  Contour plotting works as follows:

!Wol_start
  1. the "-> &FIELD -> 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:
!Wul_start
     - the maximum number of steps is reached;
     - the contour passes a second time its starting point;
     - the contour leaves the area, enters a wire etc.;
     - no continuation of the contour can be found.
!Wul_end
!Wol_end

  Format:
!W
  ! CONTOUR-PARAMETERS [ "-> graphics -> CONTOUR-PARAMETERS -> BISECTION-ITERATIONS" n_bisection ] ...
                       [ "-> graphics -> CONTOUR-PARAMETERS -> EPSILON-GRADIENT" \ε-gradient ] ...
                       [ "-> graphics -> CONTOUR-PARAMETERS -> EPSILON-TRACING" \ε_tracing ] ...
                       [ "-> graphics -> CONTOUR-PARAMETERS -> GRID-TOLERANCE" tol ] ...
                       [ "-> graphics -> CONTOUR-PARAMETERS -> NEWTON-ITERATIONS" n_Newton ] ...
                       [ "-> graphics -> CONTOUR-PARAMETERS -> STEP-MAXIMUM" steps ]
!W


  Example:
!W
  area -0.01 -0.01 0.01 0.01
  !cont-par eps-gra 1e-4 eps-tra 1e-4
  plot cont V
!W


  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\.
3 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]
3 EPSILON-GRADIENT
  The \ε 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\]
3 EPSILON-TRACING
  The \ε 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\]
3 GRID-TOLERANCE
  Since the contours are computed as piecewise straight lines
  while the true contour is curved, it can be that a computed
  segment does not pass between the same grid points where the
  true contour passes.

  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]
3 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]
3 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]
2 DEACTIVATE-WORKSTATION
  Deactivates a "-> graphics -> workstation". 

  After this operation, the workstation is in the GKS state 'open'.
  This means that it will still be known to Garfield and GKS, but
  it will not receive any graphics output. The workstation can then
  be closed via !"-> graphics -> CLOSE-WORKSTATION" or re-activated
  by !"-> graphics -> ACTIVATE-WORKSTATION".

  A workstation can only be deactivated if it is in the "active"
  state.

  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:
!W
  ! DEACTIVATE-WORKSTATION workstation
!W


  Example:
!W
  ! deact terminal
!W


  Temporarily suspends graphics output to the terminal.
2 DELETE-WORKSTATION
  Deletes a "-> graphics -> workstation" from the workstation tables.

  Before this operation, the workstation should be in the state "open".
  If !DELETE-WORKSTATION is invoked for a workstation that is still in
  the state "open" or "active", then !"-> graphics -> CLOSE-WORKSTATION"
  will automatically be called before deleting the workstation.

  After this operation, all information about the workstation is lost.
  A workstation can therefore not be re-opened or re-activated after a
  !DELETE-WORKSTATION - it would first have to be re-added to the
  workstation table with !"-> graphics -> ADD-WORKSTATION".

  !DELETE-WORKSTATION does not delete a metafile that might be attached
  to the workstation.

  Format:
!W
  ! DELETE-WORKSTATION workstation
!W


  Example:
!W
  !delete metafile
!W


  You opened the metafile by accident and decide you don't need
  a metafile at all during this run.
2 EXIT
  Leaves the graphics subsection.

  Format:
!W
  EXIT
!W

2 GET-COLOURS
  Reads a list of colours from a dataset which has been written by
  a call to "-> graphics -> 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
  "-> graphics -> 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:
!W
  ! GET-COLOURS "-> graphics -> GET-COLOURS -> file" ["-> graphics -> GET-COLOURS -> member"]
!W


  Examples:
!W
  !GET-COL TEST PARROT
!W


  Picks up the member PARROT on dataset TEST.
3 file
  The name of the "-> dataset -> structure -> file" that contains
  the colour description.
3 member
  The name of the "-> dataset -> structure -> member" that you
  wish to retrieve.
2 GET-REPRESENTATION
  Loads a representation table from a dataset written by the
  "-> graphics -> WRITE-REPRESENTATION" command. Any data that you may
  have entered using "-> graphics -> 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 "-> graphics -> GET-COLOURS" commands
  should precede !GET-REPRESENTATION commands. Items that reference an
  undefined colour will be shown with a colour set to FOREGROUND.

  Format:
!W
  ! GET-REPRESENTATION "-> graphics -> GET-REPRESENTATION -> file" ["-> graphics -> GET-REPRESENTATION -> member"]
!W


  Example:
!W
  !GET-REP TEST MG*
!W


  Picks up the first member that matches MG*, presumably MG600.
3 file
  The name of the "-> dataset -> structure -> file" that contains
  the representation table.
3 member
  The name of the "-> dataset -> structure -> member" that you
  wish to retrieve.
2 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:
!W
  ! INQUIRE-DEFERRAL-UPDATE-STATE
!W


  Example:
!W
  !inq-def
!W

2 INQUIRE-LEVEL
  Informs you about the level of the GKS the program is running with.

  Format:
!W
  !INQUIRE-LEVEL
!W

2 INQUIRE-OPERATING-STATE
  Tells you in which state GKS is at the moment.

  Format:
!W
  !INQUIRE-OPERATING-STATE
!W

2 INQUIRE-WORKSTATIONS
  Lists the known workstations, their states and associated files.

  Format:
!W
  !INQUIRE-WORKSTATIONS
!W

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

  By default, Garfield plots occupy the entire NDC frame: the actual
  image 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.
  The so-called viewport, or the part of the NDC frame occupied by the
  image, labels, numbers, comments, stamp and title can be reduced
  with the "-> graphics -> VIEWPORT" graphics command.

  Format:
!W
  !LAYOUT [ "-> graphics -> LAYOUT -> X-NUMBER"  x_number ] ...
          [ "-> graphics -> LAYOUT -> Y-NUMBER"  y_number ] ...
          [ "-> graphics -> LAYOUT -> X-DECADE"  x_decade ] ...
          [ "-> graphics -> LAYOUT -> Y-DECADE"  y_decade ] ...
          [ "-> graphics -> LAYOUT -> X-LABEL"   x_label ] ...
          [ "-> graphics -> LAYOUT -> Y-LABEL"   x_label ] ...
          [ "-> graphics -> LAYOUT -> TITLE"     title ]
!W


  The parameters are graphically illustrated in the
  "-> graphics -> LAYOUT -> diagram".
3 diagram
!WIn red the adjustable parameters:
!W

!W

!W
!W

!WThe diagram has been made with a viewport covering the entire NDC
!Wspace and using the following layout settings:
!W
!W!layout x-number = 0.015, x-decade = 0.025, ...
!W        y-number = 0.007, y-decade = 0.015, ...
!W        x-label  = 0.010, y-label  = 0.010, ...
!W        title    = 0.010
!W

!W

!D2
  The diagram can be seen at the URL
  http://cern.ch/garfield/figures/layout.gif
3 X-NUMBER
  Margin between the x-axis and the upper edge of the
  numbers shown along the x-axis.

  The numbers are plotted centred horizontally at the
  coordinate they represent.

  The size of the numbers can be controlled with the
  "-> graphics -> REPRESENTATION -> item -> NUMBERS"
  representation.

  [Initial setting: 0.007]
3 Y-NUMBER
  Margin between the y-axis and the right edge of the
  numbers shown along the y-axis.

  The numbers are plotted centred vertically at the
  coordinate they represent.

  The size of the numbers can be controlled with the
  "-> graphics -> REPRESENTATION -> item -> NUMBERS"
  representation.

  [Initial setting: 0.007]
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 centred 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 controlled with the
  "-> graphics -> REPRESENTATION -> item -> NUMBERS"
  representation.

  [Initial setting: 0.015]
3 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 centred 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 controlled with the
  "-> graphics -> REPRESENTATION -> item -> NUMBERS"
  representation.

  [Initial setting: 0.015]
3 X-LABEL
  Margin between the lower edge of the viewport 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 controlled with the
  "-> graphics -> REPRESENTATION -> item -> LABELS"
  representation.

  [Initial setting: 0.01]
3 Y-LABEL
  Margin between the left edge of the viewport 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 controlled with the
  "-> graphics -> REPRESENTATION -> item -> LABELS"
  representation.

  [Initial setting: 0.01]
3 TITLE
  Margin between the top edge of the viewport and the title.

  The title is plotted left-aligned with the coordinate
  frame.

  The size of the characters can be controlled with the
  "-> graphics -> REPRESENTATION -> item -> TITLE"
  representation.

  [Initial setting: 0.01]
2 MAP-COLOURS
  Plots a table of the currently defined colours.

  Format:
!W
  !MAP-COLOURS
!W

2 OPEN-WORKSTATION
  Opens a "-> graphics -> workstation". The argument is an alphanumeric
  string designating the workstation.

  A workstation to be opened must already have been defined, for instance
  via !"-> graphics -> ADD-WORKSTATION". After !OPEN-WORKSTATION, the
  workstation is in the GKS state 'open' and can be activated by means of
  !"-> graphics -> ACTIVATE-WORKSTATION".

  Format:
!W
  ! OPEN-WORKSTATION workstation
!W


  Example:
!W
  !add falco type falco
  !open falco
  !act falco
!W


  This example shows how to add, open and activate a workstation
  named FALCO of type FALCO.
2 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 etc.

  Format:
!W
  ! OPTIONS ["-> graphics -> OPTIONS -> GRID" | NOGRID] ...
            ["-> graphics -> OPTIONS -> DECADES-ONLY" | COMPLETE-GRID] ...
            ["-> graphics -> OPTIONS -> TIME-STAMP" | NOTIME-STAMP] ...
            ["-> graphics -> OPTIONS -> LOGARITHMIC-X" | LINEAR-X] ...
            ["-> graphics -> OPTIONS -> LOGARITHMIC-Y" | LINEAR-Y] ...
            ["-> graphics -> OPTIONS -> CLEAR-BEFORE-PLOT" | NOCLEAR-BEFORE-PLOT] ...
            ["-> graphics -> OPTIONS -> CLEAR-AFTER-PLOT" | NOCLEAR-AFTER-PLOT] ...
            ["-> graphics -> OPTIONS -> WAIT-BEFORE-PLOT" | NOWAIT-BEFORE-PLOT] ...
            ["-> graphics -> OPTIONS -> WAIT-AFTER-PLOT" | NOWAIT-AFTER-PLOT] ...
            ["-> graphics -> OPTIONS -> DISPLAY-CONTROL-CHARACTERS" | EXECUTE-CONTROL-CHARACTERS] ...
            ["-> graphics -> OPTIONS -> CLIP-AREAS" | NOCLIP-AREAS] ...
            ["-> graphics -> OPTIONS -> CLIP-LINES" | NOCLIP-LINES] ...
            ["-> graphics -> OPTIONS -> CLIP-MARKERS" | NOCLIP-MARKERS] ...
            ["-> graphics -> OPTIONS -> CLIP-TEXT" | NOCLIP-TEXT]
!W


  Example:
!W
  !"-> graphics -> options" "-> graphics -> options -> grid"
!W


  (The plots that follow will have a grid overlaid.)
3 LOGARITHMIC-X
  Requests the x-axis be logarithmic in the following plot.

  This option is also set by various commands - it may therefore happen that your
  request is overruled. E.g. some gas plots have forced logarithmic scales, the
  logarithmic and linear options are reset when these plots are produced.
3 LOGARITHMIC-Y
  Requests the y-axis be logarithmic in the following plot.

  This option is also set by various commands - it may therefore happen that your
  request is overruled. E.g. some gas plots have forced logarithmic scales, the
  logarithmic and linear options are reset when these plots are produced.
3 GRID
  Requests a grid be overlaid on the following plots, which
  can make reading the values easier.

  The grid is plotted with the representation
  "-> graphics -> REPRESENTATION -> item -> GRID".

  In Cartesian log scale plots covering more than 1 decade,
  you can further choose whether you wish to have only the
  decade grid lines ("-> graphics -> OPTIONS -> DECADES-ONLY")
  or all grid lines (COMPLETE-GRID).

  [By default, no grid is displayed.]
3 DECADES-ONLY
  Specifies that, in a Cartesian plot with a log scale covering
  more than 1 decade, only the decade grid lines are to be plotted
  and not the grid lines for 2, 3,\ ...\ 9 times the decade.

  The opposite, COMPLETE-GRID, requests all grid lines to be shown.

  This option has effect only when the "-> graphics -> OPTIONS -> GRID"
  option is in effect.

  [Initially, COMPLETE-GRID is selected.]
3 TIME-STAMP
  Requests a time stamp be displayed on each plot. The string
  displayed in the time stamp can be modified with the 
  "-> graphics -> 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.]
3 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 
  NO"-> graphics -> OPTIONS -> CLEAR-AFTER-PLOT" options.
3 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 
  "-> graphics -> OPTIONS -> CLEAR-BEFORE-PLOT", also be used to
  overlay two consecutive plots.

  When overlaying plots, it is advisable to use the
  "-> graphics -> REPRESENTATION" command to set the colours of the
  "-> graphics -> REPRESENTATION -> item -> TITLE", the
  "-> graphics -> REPRESENTATION -> item -> LABELS" and the
  "-> graphics -> REPRESENTATION -> item -> NUMBERS"
  to BACKGROUND in all but the last plot.

  Example:
!W
  !"-> graphics -> options" noclear-after no"-> graphics -> options -> wait-after-plot"
  !"-> graphics -> representation" "-> graphics -> REPRESENTATION -> item -> title" text-colour background
  !rep "-> graphics -> REPRESENTATION -> item -> numbers" text-colour background
  !rep "-> graphics -> REPRESENTATION -> item -> labels" text-colour background

  "-> &FIELD"
  "-> &FIELD -> area" -1 -1 1 1
  "-> &FIELD -> plot-field" cont v

  !"-> graphics -> options" no"-> graphics -> options -> clear-before-plot"
  !rep "-> graphics -> REPRESENTATION -> item -> numbers" text-colour foreground
  !rep "-> graphics -> REPRESENTATION -> item -> labels" text-colour foreground

  "-> &DRIFT"
  "-> &DRIFT -> area" -1 -1 1 1
  "-> &DRIFT -> drift" wire

  !rep "-> graphics -> REPRESENTATION -> item -> title" text-colour red
  !"-> graphics -> options" "-> graphics -> options -> wait-after-plot"
  Call "-> Call -> GKS_select_nt"(0)
  Call "-> Call -> plot_text"(0.1,0.95,`My own title`,`title`)
  Call "-> Call -> plot_end"

  !"-> graphics -> options" "-> graphics -> options -> clear-before-plot"
!W

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

!Wol_start
  a. 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.
  b. 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.
  c. Greek letters, diacritics and ligatures are accessible as SGML
     "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> HIGZ -> entities",
     e.g. &Ksi; é and ß. For a list of SGML entities,
     see for instance: http://home.eclipse.net/~lionheart/html/entities.html
  d. Superscript and subscript can be produced using SGML
     "-> graphics -> REPRESENTATION -> text_attributes -> TEXT-FONT -> HIGZ -> tags",
     e.g. 55Fe and CO2.
!Wol_end

  [The default is DISPLAY-CONTROL-CHARACTERS.]
3 CLIP-AREAS
  This option has currently no effect.

  [This option is on by default.]
3 CLIP-LINES
  Most line plotting procedures, both those used internally by Garfield
  and "-> Call -> PLOT_LINE" remove portions which are located outside
  the main plot window and which could therefore overlap with the labels
  and the numbers along the axes.

  If you wish to plot lines in these areas, then you've to switch this
  option off - otherwise plots will look more clean if you leave the option
  switched on.

  [This option is on by default.]
3 CLIP-MARKERS
  Most marker plotting procedures, both those used internally by Garfield
  and "-> Call -> PLOT_MARKERS" remove markers which are located outside
  the main plot window and which could therefore overlap with the labels
  and the numbers along the axes.

  If you wish to plot markers in these areas, then you've to switch this
  option off - otherwise plots will look more clean if you leave the option
  switched on.

  Note that markers are either plotted entirely or not at all. This option
  does not control removing parts of a marker that are outside the main
  plot window.

  [This option is on by default.]
3 CLIP-TEXT
  This option has currently no effect.

  [This option is on by default.]
2 REPRESENTATION
  This command enables you to change the appearance of the various
  components, here called "-> graphics -> REPRESENTATION -> item"s,
  of the plot such as the box and tickmarks, drift-lines, isochrons,
  contours, titles, functions etc. Each item is plotted using one or
  more of the graphics primitives: polyline, text, polymarker or fill
  area. Each primitive has a series of attributes. For instance, the
  title of the plot is a piece of text of which you can change the text
  attributes, i.e. the font, the colour, the character quality, size,
  spacing and expansion.

  Per REPRESENTATION statement, you may modify only one item; if an
  item consists of more than one primitive, you are further restricted
  to the attributes of only one of these primitives.

  Each item has a preset representation in black and white. These are
  usually overwritten at startup by the various
!D2
  initialisation files, examples of which can be found at the URL
  http://cern.ch/garfield/files/#init.
!W
!Winitialisation files.

  If the attributes are omitted, the current representation is shown.
  If the item is omitted, all representations are displayed.

  Format:
!W
  ! REPRESENT item attribute value attribute value ...
!W


  Examples:
!W
  !rep "-> graphics -> REPRESENTATION -> item -> title" text-font -7, text-precision stroke, text-colour red, ...
             character-height 0.03
!W


  This ensures 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.
!W
  !rep "-> graphics -> REPRESENTATION -> item -> isochron" linetype solid polyline-colour blue
  !rep "-> graphics -> REPRESENTATION -> item -> isochron" polymarker-colour blue
  !rep "-> graphics -> REPRESENTATION -> item -> isochron"
!W


  This shows how isochrons can be plotted in blue. Isochrons consist
  both of lines segments and single points, hence two statements are
  needed: polyline and polymarker. The last line inquires the representation
  of the isochrons. Both the polyline and polymarker attributes are shown.
3 item
  Items are the basic components of the plot.

  Most items (e.g. the title of the plot) are drawn using only 1
  primitive (in this case, text). Some items however (e.g. an error
  bar) are drawn using several primitives (fill area and polyline,
  in this case).

  In the list below, no distinction is made between the primitives
  via which the items are plotted. You're not allowed though, to
  update in a single REPRESENTATION statement, attributes belonging
  to different primitives.
4 ASTERISK
  Polymarker item: can be used as marker type argument to the 
  "-> Call -> PLOT_MARKERS" procedure.

  Is initialised to be an asterisk, of which you can change the
  size and colour.
4 ATTACHMENT
  Polymarker item: Marks the location of an attaching interaction between
  an electron and a gas molecule, as a result of which the electron will
  as a rule be lost.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 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 \δ-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.
4 BARCHART-1
  Fill area item: used to plot the 1st bar chart in a frame.
4 BARCHART-2
  Fill area item: used to plot the 2nd bar chart in a frame.
4 BARCHART-3
  Fill area item: used to plot the 3rd bar chart in a frame.
4 BARCHART-4
  Fill area item: used to plot the 4th bar chart in a frame.
4 BARCHART-5
  Fill area item: used to plot the 5th bar chart in a frame.
4 BARCHART-6
  Fill area item: used to plot the 6th bar chart in a frame.
4 BARCHART-7
  Fill area item: used to plot the 7th bar chart in a frame.
4 BOX-TICKMARKS
  Polyline and fill area item: the polyline item corresponds to
  the coordinate axes, the fill area item is used in
  "-> &FIELD -> AREA -> 3D" diagrams for the 3 backmost panels
  of the box.

  The fill area item should in principle have an interior style
  of "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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.
4 CIRCLE
  Polymarker item: can be used as marker type argument to the 
  "-> Call -> PLOT_MARKERS" procedure.

  Is initialised to be a circle, of which you can change the
  size and colour.
4 COMMENT
  Polyline and text item: the polyline representation is used to
  clarify the "-> &DRIFT -> DRIFT -> TRACK -> graph"s made by the
  "-> &DRIFT -> DRIFT" command by drawing a vertical separation
  line between sections of the graph with different drift-line
  status.

  The text item is used for
!Wul_start
  - indicating the drift-line status in the above graphs;
  - the description of the viewing "-> &FIELD -> AREA -> plane" in 
    "-> &FIELD -> AREA -> CUT" plots provided the viewing
    "-> &FIELD -> AREA -> plane" is not z=0;
  - the 4 information areas underneath the title of every plot.
!Wul_end

  The latter 4 areas are used for:
!Wul_start
  - the cell and gas identifiers as set of the
    "-> &CELL -> CELL-IDENTIFIER" and "-> &GAS -> GAS-IDENTIFIER";
  - statistical information when plotting histograms;
  - other information concerning the plot such as particle being
    drifted, isochron intervals, electrode description,
    fit quality etc.
!Wul_end
  The "-> Call -> PLOT_COMMENT" procedure enables you to place labels
  of your own in the 4 area.
4 CONDUCTORS-1
  Fill area item: conductors in the chamber as entered with the
  "-> &CELL -> SOLIDS" statement, but also the wires when asking
  for a "-> &FIELD -> AREA -> 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 "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 CONDUCTORS-2
  Fill area item: conductors in the chamber as entered with the
  "-> &CELL -> SOLIDS" statement and for which a representation
  with this type was explicitly requested.

  This representation is used as such if the chamber is shown
  as a "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 CONDUCTORS-3
  Fill area item: conductors in the chamber as entered with the
  "-> &CELL -> SOLIDS" statement and for which a representation
  with this type was explicitly requested.

  This representation is used as such if the chamber is shown
  as a "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 CONTOUR-HIGHLIGHT
  Polyline item: the highlighted contours as made by the
  PLOT-FIELD commands in the field, drift and signal sections.
4 CONTOUR-LABELS
  Text item: the function values shown on the contours plotted
  by PLOT-FIELD commands, if contour labelling has been requested.
4 CONTOUR-NORMAL
  Polyline item: the normal contours as made by the
  PLOT-FIELD commands in the field, drift and signal sections.
4 CROSS
  Polymarker item: can be used as marker type argument to the 
  "-> Call -> PLOT_MARKERS" procedure.

  Is initialised to be a cross, of which you can change the
  size and colour.
4 C-WIRES
  Polymarker item: the wires of "-> &CELL -> ROWS -> label" C
  are plotted using this representation provided the
  "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in effect.

  If this option is not active, then the wires will be shown
  with "-> graphics -> REPRESENTATION -> item -> WIRES".
4 DASHED
  Polyline item: can be used as argument in procedures such as
  "-> Call -> PLOT_LINE" and "-> Call -> PLOT_ARROW" whenever
  a polyline representation is needed.

  The representation is not used by normal Garfield commands.
4 DASH-DOTTED
  Polyline item: can be used as argument in procedures such as
  "-> Call -> PLOT_LINE" and "-> Call -> PLOT_ARROW" whenever
  a polyline representation is needed.

  The representation is not used by normal Garfield commands.
4 DELTA-ELECTRON
  Polyline and polymarker item: \δ-electrons resemble
  grass 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 \δ-electron generates several further electrons,
  then it will be drawn as a line, otherwise as a marker.
4 DIELECTRICA-1
  Fill area item: the dielectric media in the chamber as entered
  with the "-> &CELL -> SOLIDS" statement.

  This representation is used as such if the chamber is shown
  as a "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 DIELECTRICA-2
  Fill area item: the dielectric media in the chamber as entered
  with the "-> &CELL -> SOLIDS" statement and for which this
  representation was explicitly requested.

  This representation is used as such if the chamber is shown
  as a "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 DIELECTRICA-3
  Fill area item: the dielectric media in the chamber as entered
  with the "-> &CELL -> SOLIDS" statement and for which this
  representation was explicitly requested.

  This representation is used as such if the chamber is shown
  as a "-> &FIELD -> AREA -> CUT" view.

  For "-> &FIELD -> AREA -> 3D" impressions, the interior style
  should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be seen with the "-> graphics -> SHADING-MAP"
  graphics command.

  The elements of the field map are shown with a separate set
  of representations: 
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-1",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-2",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-3",
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-4" and
  "-> graphics -> REPRESENTATION -> item -> MATERIAL-5".
4 DOT
  Polymarker item: can be used as marker type argument to the 
  "-> Call -> PLOT_MARKERS" procedure.

  Is initialised to be a dot, of which you can change the
  representation.
4 DOTTED
  Polyline item: can be used as argument in procedures such as
  "-> Call -> PLOT_LINE" and "-> Call -> PLOT_ARROW" whenever
  a polyline representation is needed.

  The representation is not used by normal Garfield commands.
4 E-DRIFT-LINE
  Polyline item: Electron drift-lines.
4 ELASTIC
  Polymarker item: Marks the location of an elastic interaction between
  an electron and a gas molecule. During such interactions, electrons
  neither lose nor gain energy, they are not lost and they do not produce
  additional electrons.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 ERROR-BAND
  Polyline and fill area: Error bands plotted with the
  "-> Call -> PLOT_ERROR_BAND" procedure call. 
4 ERROR-BAR
  Polyline and fill area: Error bars plotted with the "-> Call -> PLOT_ERROR_BAR"
  and "-> Call -> PLOT_OBLIQUE_ERROR_BAR" procedure calls. Although usually
  called by the user, these procedures are also used by the fitting routines
  when making graphs.

  Colour combinations offering good contrast include:

!W
!D9
  ------------------------
  polyline      fill area
  ------------------------
  orange        yellow
  brown         orange
  dark-green    copper
  blue          light-blue
  purple        light-pink
  ------------------------
4 EXCITATION
  Polymarker item: Marks the location of an inelastic interaction between
  an electron and a gas molecule which leave the gas molecule in an excited
  state. The electrons lose energy in such interactions, but they do not
  produce additional electrons and they are not lost either.

  Inelastic interactions that do not lead to an excited state are plotted with the
  "-> graphics -> REPRESENTATION -> item -> INELASTIC" representation.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 FUNCTION-1
  Polyline, polymarker, text and fill area item: 

  The polyline and polymarker items are used for the primary graph in
  almost every graph that Garfield makes.

  The text and fill area items are not used by Garfield, and are mainly
  provided for use with user procedure calls. Usually, all items are set
  to share the same colour so as to make it clear that they belong together.

  This representation is commonly used in scripts.
4 FUNCTION-2
  Polyline, polymarker, text and fill area item: 

  The polyline and polymarker types are used for the secondary graph in a plot,
  for instance the integrated diffusion in the x(t) plot or the transverse
  diffusion in the gas plots.

  The text and fill area items are not used by Garfield, and are mainly
  provided for use with user procedure calls. Usually, all items are set
  to share the same colour so as to make it clear that they belong together.

  This representation is commonly used in scripts.
4 FUNCTION-3
  Polyline, polymarker, text and fill area item: 

  The polyline and polymarker types are used in a few plots where one needs
  3 graphs in the same plot, such as the drift velocity graphs.

  The text and fill area items are not used by Garfield, and are mainly
  provided for use with user procedure calls. Usually, all items are set
  to share the same colour so as to make it clear that they belong together.

  This representation is commonly used in scripts.
4 FUNCTION-4
  Polyline, polymarker, text and fill area item:

  The polyline type is used for the cross section and energy distribution
  plots of Magboltz. The other types are not used by Garfield.

  This representation is commonly used in scripts.
4 FUNCTION-5
  Polyline, polymarker, text and fill area item: not yet used by Garfield, 
  can be used for user plots.
4 FUNCTION-6
  Polyline, polymarker, text and fill area item: not yet used by Garfield, 
  can be used for user plots.
4 FUNCTION-7
  Polyline, polymarker, text and fill area item: not yet used by Garfield, 
  can be used for user plots.
4 GOTHIC
  Text item: intended for user applications, the font of the
  representation is set to Gothic.

  Not all graphics systems will recognise this representation.
4 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.
4 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.
4 GRID
  Polyline used to draw the coordinate grid on the plots.

  The grid is shown only if the 
  "-> graphics -> OPTIONS -> GRID" graphics option is
  in effect.
4 HISTOGRAM-1
  Polyline item: used to plot the 1st histogram in a frame.
4 HISTOGRAM-2
  Polyline item: used to plot the 2nd histogram in a frame.
4 HISTOGRAM-3
  Polyline item: used to plot the 3rd histogram in a frame.
4 HISTOGRAM-4
  Polyline item: used to plot the 4th histogram in a frame.
4 HISTOGRAM-5
  Polyline item: used to plot the 5th histogram in a frame.
4 HISTOGRAM-6
  Polyline item: used to plot the 6th histogram in a frame.
4 HISTOGRAM-7
  Polyline item: used to plot the 7th histogram in a frame.
4 INELASTIC
  Polymarker item: Marks the location of an inelastic interaction between
  an electron and a gas molecule. Electrons lose energy in such interactions,
  but they do not produce additional electrons and they are not lost either.

  Inelastic interactions that lead to an excited state are plotted with the
  "-> graphics -> REPRESENTATION -> item -> EXCITATION" representation.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 IONISATION
  Polymarker item: Marks the location of an ionising interaction between
  an electron and a gas molecule as a result of which in general one or
  more additional electrons are created.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 ION-DRIFT-LINE
  Polyline item: used for ion drift-lines.
4 ISOCHRON
  Polyline and polymarker item: the isochrons in a drift
  line plot.

  With the initial default settings, i.e. when the
  "-> &DRIFT -> INTEGRATION-PARAMETERS -> DRAW-ISOCHRONS" option
  is on, an attempt is made to link the points on an isochron
  with lines.

  When a point on an isochron can not be linked to another 
  point of the same contour, and also when the
  "-> &DRIFT -> INTEGRATION-PARAMETERS -> MARK-ISOCHRONS"
  option is on, a marker is plotted on the drift-line.
4 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 "-> graphics -> REPRESENTATION -> item -> NUMBERS".

  The location of the labels can be adjusted using the
  "-> graphics -> LAYOUT" command.

  All graphs produced with normal commands have labels along their
  axes. Usually, you have no influence on the text shown there.
  However, you can make these labels invisible by setting the text
  colour to BACKGROUND and put other labels in place with the
  help of the "-> Call -> PLOT_X_LABEL" and
  "-> Call -> PLOT_Y_LABEL" procedures.
4 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
  "-> &CELL -> FIELD-MAP -> PLOT-MAP" has been requested in
  the "-> &CELL -> FIELD-MAP" command.

  Solids are shown with a separate set of representations:
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3".
4 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
  "-> &CELL -> FIELD-MAP -> PLOT-MAP" has been requested in
  the "-> &CELL -> FIELD-MAP" command.

  Solids are shown with a separate set of representations:
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3".
4 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
  "-> &CELL -> FIELD-MAP -> PLOT-MAP" has been requested in
  the "-> &CELL -> FIELD-MAP" command.

  Solids are shown with a separate set of representations:
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3".
4 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
  "-> &CELL -> FIELD-MAP -> PLOT-MAP" has been requested in
  the "-> &CELL -> FIELD-MAP" command.

  Solids are shown with a separate set of representations:
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3".
4 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
  "-> &CELL -> FIELD-MAP -> PLOT-MAP" has been requested in
  the "-> &CELL -> FIELD-MAP" command.

  Solids are shown with a separate set of representations:
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2" and
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3".
4 MESSAGE
  Text item: used for graphics messages. The most common examples
  are:
!Wul_start
  - The line asking you to hit return to signal to the program
    that it can continue. This line is shown only when using
    certain graphics systems, provided the
    "-> graphics -> OPTIONS -> WAIT-AFTER-PLOT" graphics option
    is active.
  - The time "-> graphics -> STAMP", which is shown when the
    "-> graphics -> OPTIONS -> TIME-STAMP" graphics option
    is active.
!Wul_end
4 NUMBERS
  Text item: the numbers along the coordinate axes. This item
  also covers the exponent if the scale is more than 1 decade.
4 OTHER-WIRES
  Polymarker item: the wires with "-> &CELL -> ROWS -> label"
  other than S, P and C are plotted using this representation
  if the "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in
  effect.

  If this option is not active, then the wires will be shown
  with "-> graphics -> REPRESENTATION -> item -> WIRES".
4 OUTLINE
  Polyline item: the outer limits of the solids as shown in
  "-> &FIELD -> AREA -> 3D" and "-> &FIELD -> AREA -> CUT" type
  plots if the "-> &FIELD -> AREA -> OUTLINE" option is in
  effect.
4 OUTSIDE-AREA
  Fill area item: used for areas in "-> &FIELD -> AREA -> CUT"
  type layout plots which are not part of the area
  "-> &FIELD -> AREA -> box".
4 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.
4 PLANES
  Polyline and fill area item: the planes as entered in the cell 
  section with the "-> &CELL -> PLANE" statement. The fill area
  item is used in "-> &FIELD -> AREA -> 3D" layouts, the polyline
  item is used for other projections and the outlines.

  Strips on the planes, if defined, are shown using the
  "-> graphics -> REPRESENTATION -> item -> STRIPS" representation.

  The fill area representation should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be examined with the "-> graphics -> SHADING-MAP"
  graphics command.
4 PLUS
  Polymarker item: can be used as marker type argument to the 
  "-> Call -> PLOT_MARKERS" procedure.

  Is initialised to be a plus sign, of which you can change
  the size and colour.
4 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.
4 P-WIRES
  Polymarker item: the wires of "-> &CELL -> ROWS -> label" P
  are plotted using this representation provided the
  "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in effect.

  If this option is not active, then the wires will be shown
  with "-> graphics -> REPRESENTATION -> item -> WIRES".
4 SOLID
  Polyline item: can be used as argument in procedures such as
  "-> Call -> PLOT_LINE" and "-> Call -> PLOT_ARROW" whenever
  a polyline representation is needed.

  The representation is not used by normal Garfield commands,
  but serves as default for several procedures.
4 STRIPS
  Polyline and fill area item: the strips of the planes and the
  tubes as entered in the cell section with the "-> &CELL -> PLANE"
  and "-> &CELL -> TUBE" statements. The fill area item is used
  in "-> &FIELD -> AREA -> 3D" layouts, the polyline item is
  used for other projections and the outlines.

  The planes themselves and the tube are shown using the
  "-> graphics -> REPRESENTATION -> item -> PLANES" and
  "-> graphics -> REPRESENTATION -> item -> TUBE" representation.

  The fill area representation should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be examined with the "-> graphics -> SHADING-MAP"
  graphics command.
4 SUPER-ELASTIC
  Polymarker item: Marks the location of a super-elastic interaction
  between an electron and a gas molecule. These are interactions in
  which the electron gains energy.

  This representation is used by the
  "-> Call -> DRIFT_MICROSCOPIC_ELECTRON" procedure.
4 S-WIRES
  Polymarker item: the wires with "-> &CELL -> ROWS -> label" S
  are plotted using this representation provided the
  "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is in effect.

  If this option is not active, then the wires will be shown
  with "-> graphics -> REPRESENTATION -> item -> WIRES".
4 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.
4 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.
4 TITLE
  Text item: the global title of the plot.

  All graphs produced with normal commands have a title at the
  top. Usually, you have no influence on the text shown there.
  However, you can make the title invisible by setting the text
  colour to BACKGROUND and put another title in place with the
  help of the "-> Call -> PLOT_TITLE" procedure.

  The location of the title can be adjusted using the
  "-> graphics -> LAYOUT" command.
4 TRACK
  Polyline and polymarker item: This can be either of 2 things:

!Wul_start
  - the straight line segment that you have entered via
    "-> &DRIFT -> TRACK"
  - the series of interaction points with the gas of the particle 
    that passes through the chamber
!Wul_end

  The two kinds of tracks coincide unless 

!Wul_start
  - the particle has too little energy to reach the end-point of
    the specified line segment
  - the particle undergoes multiple scattering and deviates from
    its original trajectory
!Wul_end

  In both cases, the track can be a point in some circumstances.
  In that event, a marker is used rather than a line.
4 TUBE
  Polyline item: the tube enclosing the wires. The tube is
  entered in the cell section with the "-> &CELL -> TUBE" statement.
  The fill area item is used in "-> &FIELD -> AREA -> 3D" layouts,
  the polyline item is used for other projections and the outlines.

  Strips on the tube, if defined, are shown using the
  "-> graphics -> REPRESENTATION -> item -> STRIPS" representation.

  The fill area representation should in principle be set to
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-INTERIOR-STYLE -> 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 "-> &FIELD -> AREA -> light" source. The
  shades can be examined with the "-> graphics -> SHADING-MAP"
  graphics command.
4 WIRES
  Fill area item: Wires are, unless the
  "-> &CELL -> OPTIONS -> WIRE-MARKERS" option is active,
  plotted as areas to allow them to be picked in the
  "-> &DRIFT -> 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 "-> graphics -> REPRESENTATION -> item -> C-WIRES",
  "-> graphics -> REPRESENTATION -> item -> OTHER-WIRES",
  "-> graphics -> REPRESENTATION -> item -> P-WIRES" or
  "-> graphics -> REPRESENTATION -> item -> S-WIRES" as
  appropriate.
3 fill_area_attributes
  Fill area, as the name suggests, means covering a potentially
  large part of the plot in some way.
4 FILL-AREA-INTERIOR-STYLE
  The FILL-AREA-INTERIOR-STYLE is the way the area is covered,
  there are 4 possibilities:
5 HATCHED
  A series of parallel lines, see also 
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-STYLE-INDEX".
5 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.
5 PATTERN
  Some pattern, see also 
  "-> graphics -> REPRESENTATION -> fill_area_attributes -> FILL-AREA-STYLE-INDEX".
5 SOLID
  The whole area is filled with the chosen colour. No pattern
  or hatch style is used.
4 FILL-AREA-STYLE-INDEX
  The hatch or pattern with which the area should be filled,
  refer to the GKS guide for a catalogue.
4 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 "-> graphics -> COLOUR" command.
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.
4 FILL-AREA-REFERENCE-POINT
  The coordinate of the point from where the pattern boxes
  are tiled to fill the area.
3 polyline_attributes
  Polylines are lines, straight or curved, closed or not.
  
  Polylines can be coloured 
  ("-> graphics -> REPRESENTATION -> polyline_attributes -> POLYLINE-COLOUR"),
  can be thick or thin 
  ("-> graphics -> REPRESENTATION -> polyline_attributes -> LINEWIDTH-SCALE-FACTOR")
  and can be dashed, dotted, dash-dotted etc. 
  ("-> graphics -> REPRESENTATION -> polyline_attributes -> LINETYPE").
4 LINETYPE
  The polyline line type describes the number of interruptions
  in the polyline. Examples are solid, dashed, dash-dotted.

!W

  [Default is SOLID.]
5 DASHED
  A series of dashes: - - - - -
5 DASH-DOTTED
  Alternating dots and dashes: .-.-.-.-.
5 DOTTED
  A series of dots: .........
5 SOLID
  A normal solid line without interruptions.
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.
4 LINEWIDTH-SCALE-FACTOR
  The width of the line, usually ignored on terminals,
  but respected in e.g. PostScript files.

  [Default is 1.]
4 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 "-> graphics -> COLOUR" command.

  [Default is FOREGROUND.]
3 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.
4 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 "-> Call -> PLOT_ERROR_BAR"
  procedure.

!W

5 ASTERISK
  A star: *
5 CIRCLE
  A circle: o
5 CROSS
  A cross: x
5 DOT
  A point: .
5 PLUS
  A plus sign: +
5 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.
4 MARKER-SIZE-SCALE-FACTOR
  The size of the marker. Note that this is a badly defined
  quantity, the actual size depends largely on the output device
  which is used.
4 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 "-> graphics -> COLOUR" command.
3 text_attributes
  The text attributes you may modify are the font, quality, character
  spacing, character horizontal vs vertical distortion, character
  height and colour attributes.
4 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.

  This attribute is ignored by some graphics systems, such as HIGZ.
4 CHARACTER-HEIGHT
  The height of the character, the width is adjusted automatically.
4 CHARACTER-SPACING
  If you wish extra spacing, ask for a number larger than 0.

  This attribute is ignored by some graphics systems, such as HIGZ.
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 "-> graphics -> COLOUR" command.
4 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.
5 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 "-> graphics -> OPTIONS -> 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://cern.ch/higz

  Example:
!W
  !rep "-> graphics -> REPRESENTATION -> item -> title" text-font times-roman text-precision high ch-height 0.05
  Call "-> Call -> plot_frame"(0,0,10,10,` `,` `,` `)
  Call "-> Call -> plot_text"(1,6,`élève`,`title`)
  Call "-> Call -> plot_text"(1,4,`Τροχια`/...
     ` Μυονιου`,`title`)
  Call "-> Call -> plot_end"
!W


  (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.)
6 fonts
  The correspondence between font numbers and font names is shown 
  in the table below:

!Wtable_start
!T+P                            R      +                        .
  --------------------------------------------------------------
  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
  ------------------------------------------------------------------
!Wtable_end
!W

!WThese fonts have the following appearance:
!W

!W

!W
!W


  Notes:
!Wol_start
  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.
!Wol_end
6 entities
  In output to a PostScript metafile, Greek characters, diacritics,
  ligatures and some special symbols can be created. This can be done
  by entering the PS octal code for the symbol, but also by using the
  SGML entity name.

!W

!W

!W
!W


  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 correspondence 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: α, β, Ζ etc. 
  The terminal \σ and alternative \θ 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.

!Wtable_start
!T+           +               +P                                                  .
  --------------------------------------------------------------------------------
  PostScript  SGML entity     Symbol
  --------------------------------------------------------------------------------
  \\366        á        \á
  \\367        Á        \Á
  \\276        â         \â 
  \\300        Â         \Â 
  \\260        à        \à
  \\265        À        \À
  \\357        å         \å 
  \\362        Å         \Å 
  \\311        ä          \ä  
  \\314        Ä          \Ä  
  \\321        ç        \ç
  \\322        Ç        \Ç
  \\323        é        \é
  \\324        É        \É
  \\327        ê         \ê 
  \\330        Ê         \Ê 
  \\325        è        \è
  \\326        È        \È
  \\331        ë          \ë  
  \\332        Ë          \Ë  
  \\333        î         \î 
  \\334        Î         \Î 
  \\335        ï          \ï  
  \\336        Ï          \Ï  
  \\370        ł        \ł, lower case l with stroke, not in HTML 3
  \\350        Ł        \Ł, upper case L with stroke, not in HTML 3
  \\337        ñ        \ñ
  \\340        Ñ        \Ñ
  \\342        ô         \ô
  \\344        Ô         \Ô
  \\371        ø        \ø
  \\351        Ø        \Ø
  \\345        ö          \ö  
  \\346        Ö          \Ö  
  \\347        û         \û 
  \\354        Û         \Û 
  \\374        ù        \ù
  \\375        Ù        \Ù
  \\355        ü          \ü  
  \\356        Ü          \Ü  
  --------------------------------------------------------------------------------
  \\361        æ         \æ, "ae" ligature
  \\341        Æ         \Æ, "AE" ligature
  \\256        fi         fi ligature, not in HTML 3
  \\257        fl         fl ligature, not in HTML 3
  \\372        œ         \œ, "oe" ligature, not in HTML 3
  \\352        Œ         \œ, "OE" ligature, not in HTML 3
  \\373        ß         \ß, German sharp "s"
  --------------------------------------------------------------------------------
  \\126 G      ς        \ς, final \σ, not in HTML 3
  \\112 G      ϑ      alternative \θ, not in HTML 3
  --------------------------------------------------------------------------------
  \\302        ´         \´, acute accent, not in HTML 3
  \\046        &           \&, ampersand
  \\047        '          \', apostrophe, not in HTML 3
  \\145 S      ≈         \≈, approximately equal
  \\100        @        \@, commercial at
  \\323 S      ©          \©, copyright symbol
  \\360 S      €          \€, euro sign
  \\257 S      ←          \↓, down arrow
  \\312        °           \° degrees, not in HTML 3
  \\044        $        $, dollar
  \\041        !          !, exclamation mark
  \\263 S      ≥            \≥, greater or equal, not in HTML 3
  \\301        `         \`, grave accent, not in HTML 3
  \\076 S      >            \>, greater than
  \\071 S      ↔          \↔, horizontal double arrow
  \\111 S      ∫           \∫, integral sign, not in HTML 3
  \\067 S      ←          \←, left arrow
  \\243 S      ≤            \≤, less or equal, not in HTML 3
  \\133        [          [, left bracket
  \\074 S      <            \<, less than
  \\043        #           #, hash
  \\144 S      ∂          \∂, partial derivative
  \\045        %        %, percent
  \\275        ‰        \‰, parts per thousand, not in HTML 3
  \\261 S      ±        \± plus-minus, not in HTML 3
  \\122 S      √         \√, radical sign, not in HTML 3
  \\065 S      →          \→, right arrow
  \\322 S      ®           \®, superscript registered trademark symbol
  \\135        ]          ], right bracket
  \\122 S      &sqrt;          \√, square root, not in HTML 3
  \\264 S      ×         \×, product, not in HTML 3
  \\324 S      ™         \™, superscript trademark symbol
  \\255 S      ↑          \↑, up arrow
  --------------------------------------------------------------------------------
!Wtable_end

  Notes:
!Wol_start
  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://www.htmlhelp.com/reference/html40/entities/
!Wol_end
6 tags
  The following SGML and pseudo-SGML tags are recognised:

!Wtable_start
!T+P             +                                              .
  --------------------------------------------------------------
  Tag            Meaning
  --------------------------------------------------------------
           Backspace one character
            Go to subscript
           End of subscript
            Go to superscript
           End of superscript
  --------------------------------------------------------------
!Wtable_end

  Note: tags are case sensitive.
5 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.
6 fonts
  The correspondence between font number and font names is 
  shown in the table:

!Wtable_start
!T+P                            R      +                        .
  --------------------------------------------------------------
  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
  --------------------------------------------------------------
!Wtable_end
4 TEXT-PRECISION
  Changes the quality of the character representation.
  GKS has 3 different qualities from which you may choose:
5 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.
5 CHARACTER
  This is the standard quality. Most attributes are respected and
  the general appearance is usually satisfactory.

  A synonym for CHARACTER is MEDIUM.
5 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.
2 RESET-COLOURS
  Resets the colour table to contain only BACKGROUND and FOREGROUND.

  Format:
!W
  !RESET-COLOURS
!W

2 SET-DEFERRAL-STATE
  Sets the deferral and update states.

  Format:
!W
  !SET-DEFERRAL-STATE ...
       { AS-SOON-AS-POSSIBLE | BEFORE-NEXT-INTERACTION-GLOBALLY | ...
         BEFORE-NEXT-INTERACTION-LOCALLY | AT-SOME-TIME } ...
       { SUPPRESSED | ALLOWED}
!W

2 SHADING-MAP
  Produces a map of the various colour shades that can be used in
  "-> &FIELD -> AREA -> 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 colours
  of the fill area representations 
  "-> graphics -> REPRESENTATION -> item -> BOX-TICKMARKS",
  "-> graphics -> REPRESENTATION -> item -> PLANES",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-1",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-2",
  "-> graphics -> REPRESENTATION -> item -> CONDUCTORS-3",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-1",
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-2" and
  "-> graphics -> REPRESENTATION -> item -> DIELECTRICA-3"
  representations that are used for one or more solids. 

  These shades are only generated during execution of the
  "-> &FIELD -> 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
  "-> &FIELD -> AREA -> COLOURS" option of the AREA command.
2 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,
  as explained in the example below.

  Whether the time stamp appears at all is controlled with the
  "-> graphics -> OPTIONS -> TIME-STAMP" graphics option.

  The string is displayed using the
  "-> graphics -> REPRESENTATION -> item -> MESSAGE"
  representation.

  Format:
!W
  ! STAMP string
!W


  Examples:
!W
  !stamp
  
  "-> Global" vc=2000
  ...
!D1
  !stamp "Vc=\{vc\}"
!R!stamp "Vc=\\{vc\\}"
!W


  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 "-> translation -> 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 "-> algebra -> variables -> substitution" of the value
  of VC is done only when the string is plotted.
2 VIEWPORT
  Shows or changes the viewport to be used for subsequent plots.

  The viewport is the part of the output surface that is used for
  displaying graphics. In the GKS model, the output surface is a
  square with corners (0,0) and (1,1). The viewport is specified
  using the coordinate system of the output surface, a system that
  is known as "normalised device coordinates" or NDC for short.

  Since Garfield allocates 0.1\ NDC units all around the actual
  graph in order to place labels, numbers and titles, the viewport
  must have a width of at least 0.2\ NDC units in x and in y.

  Some plots assume that the viewport is square, this is for instance
  the case for "-> &FIELD -> AREA -> 3D" plots of the drift and field
  area which may be distorted.

  The current viewport settings are displayed if all arguments are
  omitted.

  This command should not be confused with the "-> Call -> GKS_VIEWPORT"
  procedure.

  Format:
!W
  ! VIEWPORT xmin ymin xmax ymax
!W


  Initial settings: (0,0) to (1,1).
2 WRITE-COLOURS
  Writes a list of colours to a dataset for later
  retrieval with "-> graphics -> GET-COLOURS".

  Format:
!W
  ! WRITE-COLOURS DATASET "-> graphics -> WRITE-COLOURS -> file" ["-> graphics -> WRITE-COLOURS -> member"] [REMARK "-> graphics -> WRITE-COLOURS -> remark"]
!W


  Example:
!W
  ! WR-COL TEST.DAT PARROT "Lots of bright colours"
!W

3 file
  The name of the "-> dataset -> structure -> file" in which you wish
  to write the colour descriptions.
3 member
  The name by which you will want to reference
  the "-> dataset -> structure -> member" when retrieving it.
3 remark
  A "-> dataset -> structure -> remark" string that helps in
  identifying the member.

  The field is left blank by default.
2 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 "-> graphics -> GET-REPRESENTATION".

  Format:
!W
  ! WRITE-REPRESENTATION DATASET "-> graphics -> WRITE-REPRESENTATION -> file" ["-> graphics -> WRITE-REPRESENTATION -> member"] [REMARK "-> graphics -> WRITE-REPRESENTATION -> remark"]
!W


  Example:
!W
  ! WR-REP TEST.DAT MG600 "For Monterey terminals"
!W

3 file
  The name of the "-> dataset -> structure -> file" in which you wish
  to write the representation table.
3 member
  The name by which you will want to reference
  the "-> dataset -> structure -> member" when retrieving it.
3 remark
  A "-> dataset -> structure -> remark" string that helps in
  identifying the member.

  The field is left blank by default.
1 input
  When you start Garfield, the program performs some initialisation
  and then waits for input from the normal input stream. For jobs that
  are not likely to be repeated, one would type the various commands
  at the terminal and have them executed immediately.

  If, on the other hand, it is likely that you will re-run a given set
  of commands several times, changing perhaps a few parameters, then it
  is probably more convenient to place the set of commands in a file
  to be read by Garfield.

  To prepare such a file,
!Wul_start
  - you type in such a file using an editor, or
  - using the "-> recording" feature for input entered via the terminal,
    you create an input file starting from the commands recorded during
    the previous session.
!Wul_end

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

  Format:
!W
  < "-> input -> file" [<< "-> input -> label"] ["-> input -> arguments"]
!W


  Example:
!W
  < rpc
!W


  To read the file called "rpc" until the end of the file.
2 file
  The dataset name.

  Although this file should contain ordinary Garfield input statements,
  the "-> dataset -> structure -> file" naming conventions for Garfield
  libraries should be followed.

  The main exception is that there is no need to put the file name
  between quotes for the sole purpose of preventing case conversion.
  Like with "-> output" re-routing, the case of the file name is
  preserved.
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]
2 arguments
  Arguments you wish to have available to "-> Parse" "-> Parse -> Argument"
  statements within the file that will be read.

  [By default, a blank string.]
1 output
  Re-routs most of the output to a "-> output -> file". To revert to
  terminal output, enter the ">" command without dataset name.

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

  This command is taken care of by the low-level input reading routine.
  The section doesn't see it and doesn't know either where the output
  is being sent. You can find out whether output is being re-routing by
  examining the "-> algebra -> variables -> predefined -> OUTPUT" global
  variable.

  Format to start re-routing:
!W
  > "-> output -> file" ["-> output -> member" ["-> output -> remark"]]
!W


  Format to stop re-routing:
!W
  >
!W


  Example:
!W
  > field.map
  print ex,ey,e,v
  >
!W


  This example works in the field section. First the output is
  re-routed to the dataset FIELD.MAP, this file captures the long
  printout from the "-> &FIELD -> PRINT" command and then output
  is sent to the terminal again.
2 file
  The name of the "-> dataset -> structure -> file" to which the
  output is to be written.

  Contrary to what is usual in other commands, case is preserved
  and there is therefore no need to use "-> introduction -> quotes"
  for the sole purpose of preventing case conversion.

  [This is a mandatory parameter when starting to re-rout. No default
  is provided.]
2 member
  The name to be given to the "-> dataset -> structure -> member"
  that will contain the output.

  Like for the file name, the case of this argument is preserved,
  and quotes are not normally needed therefore.

  [This field is by default left blank.]
2 remark
  A "-> dataset -> structure -> remark" string that helps in
  identifying the member.

  Like for the file name, the case of this argument is preserved,
  and quotes are not normally needed therefore.

  [The field is by default set to "Printed output".]
1 recording
  Garfield will at your request record your terminal input.

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

  The recorded input is commonly used as "-> input" for subsequent
  runs.

  The command to start recording is:
!W
  >> "-> recording -> file"
!W


  To stop recording, type:
!W
  >>
!W


  Example:
!W
  >> a.b
  Say "Recording on a.b"
  >> c.d
  Say "Recording on c.d"
  >>
  Say "Not recording anymore"
!W

2 file
  The dataset name. The name should be enclosed in single
  "-> introduction -> 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.

  [The recording file is by default called garflast.dat or similar.]
1 shell
  Aegis, DCL, Unix and VM/CMS commands can be issued from inside the 
  program without having to exit the program. You may wish to view 
  the shell as a sub-section - like with the sub-sections, you stay
  in the shell if you omit the command.

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

  Format for a single line command:
!W
  $ [Aegis, DCL, Unix or VM/CMS instruction]
!W


  Format for an excursion:
!W
  $                 $               $                $
  (Aegis commands)  (Vax commands)  (Unix commands)  (CMS commands)
  return            LOGOUT          exit             RETURN
!W


  Examples:
!W
  $ emacs layout &

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


  Starts an emacs editing session and list the characteristics of 
  the gas file.
2 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:
!W
  return
!W

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:
!W
  LOGOUT
!W

2 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:
!W
  RETURN 
!W

2 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:
!W
  SHELL "csh"
!W


!D2
  in your initialisation file, an example of which can be found at
  the URL http://cern.ch/garfield/files/#init.
!Win your 
!Winitialisation file.

  Note the double "-> introduction -> 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:
!W
  exit 
!W

1 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.
2 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:
!W
  ESCAPE character
!W


  Example:
!W
  esc ^
!W


  (Replaces the current escape character by a caret.)
3 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:

!Wtable_start
!T+                     CP      +                   .
  --------------------------------------------------
  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 abbreviations
  asterisk              *       Comment lines
  smaller than          <       Input redirection
  larger than           >       Output redirection
  round brackets        ()      Formulae
  square brackets       []      Matrix indices
  curly brackets        {}      Formula evaluation
  --------------------------------------------------
!Wtable_end

!D1
  [The escape character is initially set to \.]
!R[The escape character is initially set to \\.]
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
  "-> algebra -> variables -> substitution" of expressions enclosed by
  curly brackets.

  Characters preceded by the escape character (by default set to
!D1
  backslash: \, see also "-> translation -> ESCAPE") are not translated.
!Rbackslash: \\, see also "-> translation -> ESCAPE") are not translated.
  

  If arguments are omitted altogether, the current translation table
  is displayed.

  Format:
!W
  TRANSLATE [CYCLES ncycle] ...
       [INTEGER | HEXADECIMAL] char_in [INTEGER | HEXADECIMAL] char_out
!W


  Example:
!W
  TRANSLATE "." "&", X Y 
!W


  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.
3 INTEGER
  Indicates the character is specified via its integer code in
  the range from 0 to 255.
3 HEXADECIMAL
  Indicated the character is specified via its hexadecimal code
  in the range from 0 to FF.
3 char_in_out
  Either a single character, perhaps enclosed by double
  "-> introduction -> quotes" to preserve case, or an integer or an
  hexadecimal number.
3 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.
2 GET-TRANSLATION-TABLE
  Retrieves the translation table from a dataset to which it has been
  written by means of a "-> translation -> WRITE-TRANSLATION-TABLE"
  command. The member name is optional if only one translation
  table has been stored in the dataset.

  Format:
!W
  GET-TRANSLATION-TABLE file [member]
!W


  Example:
!W
  GET-TRANS garflib.dat vax
!W


  Reads a member called VAX from the library GARFLIB.DAT.
3 file
  The name of the "-> dataset -> structure -> file" that contains
  the translation table.
3 member
  The name of the "-> dataset -> structure -> member" that you
  wish to retrieve.
2 WRITE-TRANSLATION-TABLE
  Writes the current translation tables to a dataset for later
  retrieval by "-> translation -> GET-TRANSLATION-TABLE". The
  keywords DATASET and REMARK are optional if the member name
  is not omitted if a remark is present.

  Format:
!W
  WRITE-TRANSLATION-TABLE DATASET file [member] [REMARK remark]
!W


  Example:
!W
  WR-TRANS trans.dat vax
!W

3 file
  The name of the "-> dataset -> structure -> file" in which you wish
  to write the translation table.
3 member
  The name by which you will want to reference
  the "-> dataset -> structure -> member" when retrieving it.
3 remark
  A "-> dataset -> structure -> remark" string that helps in
  identifying the member.

  The field is left blank by default.
! *** End of Garfield help file ***