|
|
|
These pages have a tree structure with the sections as main branches:
Garfield has a limited set of control structures that can be used at any level of program input:
It is a program that can be run both interactively and in batch on a wide variety of computers without significant change in outwards appearance. The program is fully command driven but if you desire to add some pieces, you'll find no major obstacles (the program has been written in Fortran-77 and uses Patchy as pre-processor).
Additional information on:
Main -> Cell section -> algebra sub-section
graphics sub-section
...
Gas section -> algebra sub-section
graphics sub-section
...
The &MAIN command moves you back to the top level of program input, i.e. the level at which one enters the program. This is the normal environment to execute procedure Calls which use cell or gas data, e.g. in order to calculate drift lines.
&MAIN can also be used as final statement in jobs that run Magboltz to produce electron transport plots. &MAIN is in this context approximately equivalent to &STOP.
The cell and gas sections produce plots, write data sets and make their data available to the procedures when the section is left. Leaving the section can be done in 3 ways:
Example:
Global emin=100 Global emax=10000 &MAG comp 0 0 0.4 T&GAS opt gas-plot write "p10.gas" "b4000" magboltz argon 90 methane 10 coll 2 n-e 4 n-angle 2 ... e-range {emin,emax}
&MAIN Global n=100 Global e=emin*(emax/emin)**((row(n)-1)/(n-1)) Call transverse_diffusion(e, 0, 0, 0, 0, 0.4, dt) Call longitudinal_diffusion(e, 0, 0, 0, 0, 0.4, dl) Call plot_graph(e,(dt**2+dl**2),`E [V/cm]`, ... `sqrt(σ<SUB>T</SUB><SUP>2</SUP>+σ<SUB>L</SUB><SUP>2</SUP>)`, ... `Diffusion`) Call plot_end
Without the &MAIN statement, the GAS-PLOT option would have no effect, the WRITE statement would not be executed and the various procedure calls would be rejected.
Everything you enter, is simply stored. A comprehensive check of the input is only performed when leaving the section. That is also the time the compact format cell dataset is written, if requested, the layout is plotted, the cell description is printed etc.
Format:
&CELL
Additional information on:
The cell description is not touched by this, but any existing gas data is cleared when this section is entered since the transport properties of gasses depend on the magnetic field. You must therefore enter the magnetic field before entering the gas description.
[Initially, the magnetic field is off.]
Additional information on:
Some of these properties can be computed: the Magboltz program will calculate the electron drift velocity, diffusion, Townsend and attachment coefficient for nearly arbitrary gas mixtures. The Heed program takes care of clustering, also for nearly arbitrary gas mixtures.
If you have measured gas properties, or have access to measurements you trust, you can enter this data in the form of tables. One can also replace parts of the Magboltz tables with measurements.
For rapid studies which do not require great accuracy, descriptions of a few common gas mixtures are built in to the program.
All existing gas information is cleared by entering the gas section or the magnetic field section since the transport properties of gasses depend on the magnetic field.
Format:
&GAS
Additional information on:
Format:
&OPTIMISE
Additional information on:
Format:
&FIELD
Additional information on:
The central instruction is the DRIFT command, but also ARRIVAL and XT-PLOT can be useful for a coarse chamber calibration.
Additional information on:
Since signal calculation and processing is strongly experiment dependent, this section consists only of a series of building blocks with which you can build an hopefully detailed simulation of your signal.
Additional information on:
&STOP has an advantage over an end-of-file condition in that &STOP closes the current section before ending program execution. This does not happen with end-of-file. Data that is output when the section is closed, such as gas files and gas plots, are therefore lost when end-of-file is used instead of &STOP.
A section can be closed without stopping Garfield by means of the &MAIN command.
Program execution can also terminate because errors are encountered while the ON-ERROR-TERMINATE option is in effect. Such termination is equivalent to issuing a &STOP command.
Some options can also be set from the command line.
Format:
OPTIONS [NODEBUG | DEBUG] ...
[NOIDENTIFY | IDENTIFY] ...
[NOINPUT-LISTING | INPUT-LISTING] ...
[RECORDING | NORECORDING] ...
[PROGRESS-PRINT | NOPROGRESS-PRINT] ...
[ON-ERROR-CONTINUE | ON-ERROR-SKIP | ON-ERROR-TERMINATE] ...
[NODUMP-ON-GRAPHICS-ERROR | DUMP-ON-GRAPHICS-ERROR] ...
[WARN-BUT-WRITE | WARN-AND-NOWRITE | DELETE-OLD-MEMBER ]
Example:
OPT ID
Note: Actions depending on the setting of the ON-ERROR-... options are only gradually being introduced.
Additional information on:
Call gives access to a wide variety of routines and data inside Garfield. Although originally intended as a debugging aid, procedure calls are now widely used whenever the commands do not provide sufficient flexibility.
Input arguments can be Global variables, constants or expressions in terms of global variables and/or constants. Output variables are simple global variables - not constants nor expressions. An output variables which does not exist at the time of the procedure call, will be declared automatically. An existing global variable will be overwritten by the procedure.
Procedure arguments which are used as input, must have (one of) the types shown in the description. Some procedures can accept arguments of several types. Fits, for instance, can usually be done on matrices and on histograms. The descriptions of such procedures show two or more formats - one of which must be chosen, the formats should not be mixed.
To ensure that the procedures that rely on cell and gas data work, one should call them only after the cell and gas sections have been left (e.g. via &MAIN) - it is not enough to have entered the cell and gas data, cell and gas data become available to the procedures only when the sections have been left.
Format:
CALL procedure(arg1, arg2, ... )
Examples are given in the descriptions of most procedures.
Additional information on:
Do loops are used to repeatedly execute a set of lines.
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.
Garfield also allows loops which have no such variable. These loops can only be left using the Leave statement.
Do not attempt to input a file with < while in a Do loop.
Format:
[For var From from [Step step] To to] [While while] [Until until] Do[statement | Leave [var] | Iterate [var]]
Enddo
Example:
For i from 1 to 5 do
Say "Now I has the value {I}."
Enddo
Say "Finished !"
Additional information on:
Assigns a value to a global variable. This statement can have up to 2 arguments:
Global variables are commonly used for substitution of an expression in input statements, as well as in control structures.
If the value is omitted, then the variable is declared and will be given the value Nill, i.e. it will be of type Undefined.
All currently defined globals are listed with their type and value if there are no arguments. You will see that the list includes a few predefined globals. Occasionally, you will find globals with names that do not comply with the naming conventions for variables. These are copies of globals which must be kept even if you modify the original.
If you wish to see the value of a single variable, then use Say. To list all currently known strings, matrices and histograms, use the LIST_STRINGS, LIST_MATRICES, and LIST_HISTOGRAMS procedures.
If you wish to use the type of a global variable in a formula, then use either the TYPE function or the INQUIRE_TYPE procedure. If you wish to gain access to a global variable of which you construct the name as a String, then use the GLOBAL function.
Format:
GLOBAL variable [value]
Examples:
Global my_name=`abc DEF`Global argon=80 Global ethane=20 Global member=`a`/string(argon)/`e`/string(ethane)
The first example assigns the character string "abc DEF" to the variable my_name. In the second example, a suitable member name of a compact gas description is constructed from the Argon and ethane contents. Note that no curly brackets are used.
Additional information on:
If blocks are used to conditionally execute a group of statements and to execute only one of a set of groups of statements depending on a series of conditions. If blocks may be nested and may also contain entire Do_loops in their branches.
Format:
If cond Then[Elseif cond Then]
[Else]
Endif
Example:
If vax Then
get 'disk$food:[garfield]lasagne.dat'
Elseif cray|apollo|sun Then
If Cray Then $ fetch //food/garfield/lasagne.dat ...
-t'fn=FOOD,ft=LASAGNE'
get "//food/garfield/lasagne.dat"
Elseif cms Then
get food.lasagne.*
Else
Say "No GET for this machine; stopping."
& Stop
Endif
In this example, a cell (or gas) compact description is fetched from a file - the name depends on the machine. In the case of the Cray, the file is first read from the IBM.
The If line is used to execute conditionally only one line, for instance a &STOP if the amount of CPU time left to the job is less than a few seconds. An If line is also used to conditionally execute an entire Do_loop.
Format 1:
If cond Then statement
Format 2:
If cond Then ... Dostatement | Leave [var] | Iterate [var]
Enddo
Examples:
If time_left<10 Then & Stop If vax Then Say "Running on a Vax."If x>10 Then For i From 10 To 1 Step -1 Do If 'entier(i/3+0.001)=3' Then Iterate Say "x+i/3 = {x+i/3}" Enddo
This instruction enables you to make input files that prompt for parameters. For instance, in a magnetic field section, you could ask for the value of the magnetic field and then issue a COMPONENTS instruction with the B-field the user specifies. You could also ask the user to enter the name of a cell description and then load it from a library of such descriptions.
If you're familiar with REXX, you'll note the similarity with the REXX command by the same name. Keep in mind however that the REXX syntax is far richer than what is offered here. Also, in Garfield, all input is automatically evaluated as expressions in terms of Global variables. An error results if the syntax is not correct. This could for instance happen if you try to enter character input without quotes: an attempt would be made to evaluate the string as an expression in terms of the global variables.
Format:
PARSE {GLOBAL var | INPUT | TERMINAL | VALUE expression} template
Example 1: Get the piece before and after the decimal dot of pi**2
Parse Val pi**2 int'.'frac
Example 2: Ask for a yes/no answer
&FIELD
Global yes=True
Global no=False
Say "Make a 3D plot ? (yes/no)"
Until OK Do
Parse Terminal plot_3D
Call inquire_type(plot_3D,type)
If 'type=`Logical`' Then
Global OK=True
Else
Say "Please give an answer that evaluates to True or False."
Global OK=False
Endif
Enddo
If plot_3D Then plot surface
The global variables YES and NO are set respectively to the values True and False so that the user can simply type. The user may still answer with any expression that evaluates to a Logical (e.g.: 3>4, False etc). Note that the variables YES and NO are defined in the default initialisation file.
Example 3: Ask for a cell name
Say "Please enter the name of the cell to be read:"
Parse Terminal cell
(The user responds with (note the quotes !): `DC1`)
get cell.lib {cell}
Note the use of the reverse quote in the user response: since the global variable CELL should be a string, it should be enclosed in quotes. Single and double quotes would disappear in the process since these quotes are not part of the string that is entered. An equivalent, but more clumsy, user response would have been '"DC1"', with an outer layer of single quotes to keep make the double quotes inside part of the string.
Additional information on:
Format:
SAY string
Example:
Say "Only {time_left} seconds left !"
Prints the value of a predefined global variable.
Newly created Matrices are 1-dimensional and have a length that is equal to the number of elements entered. Matrices can be given another shape with the RESHAPE_MATRIX procedure.
For existing 1-dimensional Matrices, a new vector is created that replaces the old one. For higher dimensional Matrices, however, the number of dimensions and the size are kept as they were, and new elements replace old elements in the order in which the Matrix is internally stored (opposite to the Fortran convention).
The Vector statement can read data into one or more Matrices at the time. If more than one Matrix is present, then the statement should be followed by a series of lines which contain precisely one new element of each of the Matrices. If only one Matrix is present, then one may type an arbitrary number of elements on an arbitrary number of lines following the statement. In either case, there should be a blank line to signal that all elements have been entered.
Format:
VECTOR x y z ... VECTOR x x1 y1 z1 ... x1 x2 x3 ... x2 y2 z2 ... ... ... ... xn yn zn ... ... xn (blank line) (blank line)
Example:
Vector zzz 0 1 2 3 4 5 6Call reshape_matrix(zzz,2,4,pi)
The Vector statement results in a 1-dimensional matrix of length 7, called ZZZ, which contains the numbers 0 to 6. The RESHAPE_MATRIX procedure call re-arranges this vector to a 2x4 matrix. This matrix has one element more than the original vector, which is filled with the value PI.
Additional information on:
Formulae can be typed as usual in Fortran or C, with some exceptions:
Evaluation is not as quick as compiled routines but since the formulae are preprocessed and translated into an instruction_list, the losses for repeated evaluations are small to what would otherwise be needed in terms of human time.
The translation of the formula into an instruction list, is done independent of the data type. It may also be possible that the resulting instruction list can be executed for several data types.
Instruction lists can be editted in the algebra editor which is entered by typing a @ instead of a formula. The editor behaves like a subsection. On exit of the editor, the function is used by the calling routine to perform its task.
Additional information on:
Format:
* anything you wish
Additional information on:
Although Garfield datasets are sequential files for the operating system, they have for Garfield purposes the structure of libraries composed of one or more members. A member can for instance be a compact cell description, a piece of program output or a signal in Spice readable format.
Garfield datasets can be moved between machines, you may also operate on such datasets on other computers if the OS allows.
Garfield libraries are things you would not normally wish to edit except to extract an x(t)-relation or a piece of output. Instead, the program provides a set of instructions that make directory listings, list individual members and delete members.
All dataset commands start with a % sign. If you have lots of dataset commands to do, you may prefer to enter the dataset subsection by typing only the % sign, without arguments. In the dataset subsection no % has to be prefixed to the commands. You may not enter other subsections from within the dataset subsection. EXIT will get you back to the section you came from.
Additional information on:
You should not normally see KERNLIB error messages, the instruction described below is therefore mainly useful for debugging the program.
Format:
ERROR-HANDLING MESSAGE mess-id ...
[PRINT {ALWAYS | NEVER | nprint}] ...
[ABEND {NEVER | nabend}]
mess-id Is the identifier of the message as listed in the 'green book' of CERN program library writeups. Both nprint and nabend are meaningful only in the range 0 to 100. Execution is terminated at the nabend+1 occurence of the error.
For further details, see short writeup N001: http://consult.cern.ch/shortwrups/n001/top.html
Settings that are common for most of your runs can be placed more conventiently in your initialisation file. This is for instance the case of the colours and the representations.
All graphics commands start with a ! sign. If you have lots of graphics things to do, you may prefer to enter the graphics subsection by typing only the ! sign, without arguments. In the graphics subsection no ! has to be prefixed to the commands. You may not enter other subsections from within the graphics subsection. EXIT will get you back to the section you came from.
Additional information on:
If, on the other hand, it is likely that you will re-run a given set of commands several times, changing perhaps a few parameters, then it is probably more convenient to place the set of commands in a file to be read by Garfield.
To prepare such a file,
Reading a file that contains normal input statements, is achieved with the "<" command.
Format:
< file [<< label]
Example:
< cell_section
(To read the file CELL_SECTION.DAT until the end of the file.)
Additional information on:
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 stop program execution using the &QUIT command.
Format to start rerouting:
> file [member [remark]]
Format to stop rerouting:
>
Example:
> field.map print ex,ey,e,v >
(This example works in the field section. First the output is rerouted to the dataset FIELD.MAP, this file captures the long printout from the PRINT command and then output is sent to the terminal again.)
This command is taken care of by the low-level input reading routine. The section doesn't see it and doesn't know either where the output is being sent.
Additional information on:
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 to a file called dsname is:
>> dsname
To stop recording, type:
>>
Example:
>> a.b Say "Recording on a.b" >> c.d Say "Recording on c.d" >> Say "Not recording anymore"
Additional information on:
The case of the command following the $ is preserved, hence there is normally no need to use quotes. One may perform substitution of expressions using curly brackets.
Format for a single line command:
$ [Aegis, DCL, Unix or VM/CMS instruction]
Format for an excursion:
$ $ $ $ (Aegis commands) (Vax commands) (Unix commands) (CMS commands) return LOGOUT exit RETURN
Example:
Global gas_file `Ar_DME.gas`
$ ls -l {gas_file}
Will list the characteristics of the gas file.
Additional information on:
Your terminal may also lack some keys.
The initial translation table converts tabulation characters to spaces on Vax, Alpha and Unix computers.
You may occasionally also have to bypass the translation mechanism by using or modifying the escape character.
Additional information on:
Formatted on 0100-09-02 at 06:57.