!==============================================================================! ! Introductory help file, not the help file used inside the program. ! ! This file could be part of the general help library of the system. ! ! ! ! System manager: this file contains site specific information that ! ! you should adapt to your system. ! ! ! ! This file corresponds to Garfield version 6.09 and is not backwards ! ! compatible with versions lower than 6.09. ! ! ! ! Copyright: Rob Veenhof, 1997. ! !==============================================================================! 1 GARFIELD Garfield is a program for the detailed simulation of 2-dimensional wire chambers consisting of thin wires and equipotential planes. Its main use is in the area of field, drift-line and signal calculations as well as the electrostatic optimisation of a chamber. Garfield has since version 5.01 an interface to the Magboltz program written by Steve Biagi, which permits the computation of electron transport properties in nearly arbitrary gas mixtures. Since version 6.01, Garfield also has an interface to the Heed program of Igor Smirnov which simulates the interactions of fast, charged particles with gas mixtures. Garfield, Magboltz and Heed are of the 'slow' Monte-Carlo type in the sense that these programs rarely use a poor approximation if a better one is available, even if the latter uses more CPU time. That is not to say that no efforts have been made to make these program reasonably fast. Rather, one would not normally use these programs to accumulate large statistics of drift-chamber responses. The programs can be used both in interactive mode and in batch. In either case, they are completely command driven. No knowledge about Fortran or Patchy is needed to use it. Some knowledge about the file naming conventions on a Vax is useful if you wish to save the results. The program has a comprehensive help facility built in. Documentation is accessible over WWW: http://consult.cern.ch/writeup/garfield. ! [System manager: please adapt the information below to your system !] ! ! [CERN and other institutes where the program is officially available:] ! You don't have to take special action to have access to the program. If you still have Garfield related initialisations in your LOGIN.COM, you are kindly requested to remove them. ! ! [Private versions:] ! ! The commands and logicals needed to run the program have to be defined ! every session. To achieve this, include in your LOGIN.COM the line: ! ! $ GARF*IELD :== $disk:[dir]GARFRUN.EXE ! ! Then execute your LOGIN.COM or log off and in again. To start the program, type the command: $ GARFIELD /TERMINAL=(TYPE=type,GKS_ID=gksid,CONNECTION_ID=conid) /METAFILE=(TYPE=type,GKS_ID=gksid,OFFSET=offset,NAME=name) /ATC_GKS or /DEC_GKS or /GTS_GRAL or /GKS or /HIGZ /PRO or /OLD or /NEW or /EXP /DEBUG or /NODEBUG /IDENTIFICATION or /NOIDENTIFICATION /INPUT_LISTING or /NOINPUT_LISTING /PROFILE or /NOPROFILE /PROGRESS_PRINT or /NOPROGRESS_PRINT /RECORDING or /NORECORDING /RNDM_INITIALISATION or /NORNDM_INITIALISATION 2 initialisation The following is done during program initialisation: 1. program usage is logged; 2. the command line is obtained and analysed by CLI$DLC_PARSE, the global options are set accordingly; 3. the clock is started; 4. the system global variables are defined; 5. the algebra system is initialised; 6. the graphics system is started, workstations are defined according to the command line arguments; 7. the histogram system is started; 8. the input streams are set up, if a file called GARFINIT.DAT is found in the current or login directory (SYS$LOGIN), then this file is read, after which input is taken from standard input, otherwise input starts from standard input; From the user point of view, the only interesting step is the last one: the file GARFINIT.DAT can be used to set global options, to choose the workstations in a machine independent way, to define colours and representations etc. 2 /DEBUG Requests that debugging mode is initially on, that is, also during the initialisation phase. The information displayed is of hardly any use to the casual user. Debugging mode is initially off by default. Debugging mode can be switched off and on at any time during program execution. This flag can be negated: /NODEBUG. 2 /IDENTIFICATION Tracing information will be displayed from the start of program execution. The information displayed is of hardly any use to the casual user. Tracing is initially off by default. Tracing can be switched off and on at any time during program execution. This flag can be negated: /NOIDENTIFICATION. 2 /INPUT_LISTING Requests that the input read by the program is echoed. This option is on by default for batch mode runs, and off by default in interactive runs. This flag can be negated: /NOINPUT_LISTING. 2 /RECORDING Garfield can record the commands issued from the terminal in a file called GARFLAST.DAT. If you are not interested in this, then specify /NORECORDING. This option is on by default in interactive jobs, but off in batch jobs. This qualifier can be negated: /NORECORDING. 2 /PROFILE Garfield tries, at startup, to read a file called GARFINIT.DAT from your top level directory, or if not found there, from your current directory. If you do not wish such a file to be read, then specify /NOPROFILE. This option is on by default, both in batch and in interactive jobs. This qualifier can be negated: /NOPROFILE. 2 /PROGRESS_PRINT This option enables you to monitor the progress of some commands that take a lot of CPU time. The option is on by default. This qualifier can be negated: /NOPROGRESS_PRINT. 2 /RNDM_INITIALISATION To ensure the program produces different random number sequences every run, the random number generator RNDM is called a number (determined by the time of the day) of times at the start of program execution. The number of times RNDM is called is displayed if you specify /DEBUG as well. If you prefer identical sequences, specify /NORNDM_INITIALISATION. 2 /TERMINAL Specifies the terminal type. This qualifier is meaningful only in interactive runs and is therefore ignored in batch. You can either specify the terminal by a symbolic name (such as 4014 in the example below) or by the GKS identifier. In both cases you may choose the connection identifier. Examples: $ GARFIELD /TERMINAL:TYPE=4014 This is the format to be used if you use Tektronix 4014 terminal. $ GARFIELD /TERM=(GKS_ID=-100,CONNECT=100) If you wish to use a private driver with GKS identifier -100 which needs a connection identifier of 100, then the above format should be used. The /TERMINAL qualifier can be negated (/NOTERMINAL). This can be useful when you run Garfield in interactive mode from a terminal that does not allow graphics output. You can still request metafile output (see /METAFILE) and send this to a printer. The /TERMINAL qualifier is ignored in batch. 3 TYPE This is a symbolic name for the terminal. The choice of supported values depends on the GKS which is used (GTS-GRAL, DEC, ATC-GKS, HIGZ etc). GKS_IDENTIFIER and TYPE are mutually exclusive. 4 GTS-GRAL Currently the following terminal types are recognised by Garfield in GTS-GRAL / GKS compilations. Other types can be added on request. Digital: VT100_RETROGRAPHICS VT100_SELENAR VT125_REGIS VT240_REGIS VT241_REGIS VT340 VAXSTATION Pericom: PG7800 MG600 MX2000 MX7000 MX8000 Tektronix: 4010 4012 4014 4015 4105 4107 4207 4109 4209 4111 4113 4114 4115 Falco: FALCO X-windows: X_WINDOWS X_WINDOWS_i with i=0,1, ... 9 The default is PG7800. 4 DecGKS Currently the following terminal types are recognised by Garfield in DecGKS compilations. Other types can be added on request. Digital: VT125_COLOUR VT125_BW VT240_COLOUR VT240_BW VT330 VT340 VAXSTATION_1 (=VS_1) VAXSTATION_2 (=VS_2) VS_2000 DECWINDOWS Tektronix: 4014 4017 In addition you may use LOGICAL, in which case DecGKS will look for the appropriate logical definitions - see the DecGKS manuals for more details. Default is 4014, even though the driver for 4014 in at least early releases of Dec GKS divides by zero when plotting text. Since Garfield frequently plots text in its graphs, this means that you have to provide a dummy GTX routine if you wish to use this kind of terminal output. 4 ATC-GKS Currently the following terminal types are recognised by Garfield in ATC-GKS compilations. Other types can be added on request. Digital: VT125_REGIS VT240_REGIS VT241_REGIS VT330 VT340 VT340_COLOUR RETRO Tektronix: 4010 COMP_4010 4014 4105 PIX_4105 COMP_4105 4107 12B_4107 4205 12B_4205 4208 12B_4208 4111 32B_4111 4115 32B_4115 4125 32B_4125 C-ITOH 414A: CIT_414A Graphon 140, 230: GRAPHON Imagen: LAND_IMG PORT_IMG X-windows: X11 BS_X11 (back and store) 4 HIGZ Currently the following terminal types are recognised by Garfield in ATC-GKS compilations. Other types can be added on request. INQUIRE or 0 - prompt for the workstation type 1-9 - look in HIGZ_WINDOWS.DAT 7878 or FALCO - Falco 3 GKS_IDENTIFIER The reference number inside GKS of the driver you wish to use. Check the GKS documentation for a list of drivers, or ask your system manager. Garfield checks that GKS indeed has a driver that matches your identifier, and also verifies that the driver is suitable for interactive use. GKS_IDENTIFIER and TYPE are mutually exclusive. When GKS_IDENTIFIER is specified, CONNECTION_IDENTIFIER should also be specified. 3 CONNECTION_IDENTIFIER The logical unit via which the terminal is accessed. CONNECTION_IDENTIFIER should be specified when GKS_IDENTIFIER is used, CONNECTION_IDENTIFIER can be specified together with TYPE but this is not recommended. 2 /METAFILE This qualifier lets you choose a metafile format and a metafile file name. This qualifier can be used both in batch and in interactive mode. Examples: GARFIELD /METAFILE=(TYPE=APPENDIX_E,NAME=PLOT.METAFILE) This example shows how one can create a metafile called PLOT.METAFILE which is written in the Appendix E metafile format. Similar formats can be used for the various PostScript formats. GARFIELD /METAFILE=(GKS=4,NAME=PLOT.METAFILE,OFFSET=0) In this example, the TYPE keyword is not used. Instead, the GKS identifier of the workstation is used directly together with the offset between connection identifier of the workstation and the logical unit of the metafile. This qualifier can be negated (/NOMETAFILE) in order to suppress all metafile output. 3 TYPE Symbolic name for the metafile type, the choice depends on the GKS Garfield has been linked with. GKS_IDENTIFIER and TYPE are mutually exclusive. 4 GTS-GRAL If you use a module linked with GTS-GRAL, the metafile type should be chosen from the following list: APPENDIX_E Appendix E metafile format PS_PORTRAIT_BW Black and white PostScript PS_LANDSCAPE_BW As before but rotated by 90 degrees PS_PORTRAIT_COLOUR Colour PostScript PS_LANDSCAPE_COLOUR As before but rotated by 90 degrees EPS_PORTRAIT_BW Black and white encapsulated PostScript EPS_LANDSCAPE_BW As before but rotated by 90 degrees EPS_PORTRAIT_COLOUR Colour encapsulated PostScript EPS_LANDSCAPE_COLOUR As before but rotated by 90 degrees The PostScript format, which may not formally be a standard but which is widely used, is convenient if the plot has to be sent to users at other sites. This format is reasonably compact, is easy to include in documents marked up with TeX, SGML etc. 4 DecGKS Garfield currently recognises the following metafile formats in DecGKS compilations: PostScript: POSTSCRIPT (=PS) Metafile: DECGKS_MO (=METAFILE) CGM Digital plotters: LCP01 LCG01 LN03 Hewlett-Packard plotters: HP7475 HP7550 HP7580 HP7585 Canon plotters: LBP8A2 Kyocera plotters: L880 4 ATC-GKS Garfield currently recognises the following metafile formats in ATC-GKS compilations: Computer Graphics Metafile: CGM_BIN CGM_MBIN CGM_CHAR CGM_TEXT CGM_LBIN CGM_LCHAR CGM_LTEXT ATC Postscript: PS_PORTRAIT_BW (=POSTSCRIPT) Black and white PostScript PS_LANDSCAPE_BW As before but rotated by 90 degrees PS_PORTRAIT_COLOUR Colour PostScript PS_LANDSCAPE_COLOUR As before but rotated by 90 degrees EPS_PORTRAIT_BW (=ENCAPSULATED_PS) Black and white encapsulated PostScript EPS_LANDSCAPE_BW As before but rotated by 90 degrees EPS_PORTRAIT_COLOUR Colour encapsulated PostScript EPS_LANDSCAPE_COLOUR As before but rotated by 90 degrees 4 HIGZ Garfield currently recognises the following metafile formats in HIGZ compilations: PS_LANDSCAPE Colour landscape format PostScript PS_PORTRAIT or POSTSCRIPT Colour portrait format PostScript EPS or ENCAPSULATED_PS Colour encapsulated PostScript LATEX LaTeX format metafile 3 GKS_IDENTIFIER The reference number inside GKS of the driver you wish to use. Check the GKS documentation for a list of drivers, or ask your system manager. Garfield checks that GKS indeed has a driver that matches your identifier, and also verifies that the driver is suitable for metafile type output. GKS_IDENTIFIER and TYPE are mutually exclusive. When GKS_IDENTIFIER is specified, OFFSET should also be specified. 3 OFFSET Some drivers produce a different format depending on the offset between logical unit of the driver and the connection identifier. This is for instance the case for the CERN GTS-GRAL PostScript drivers. OFFSET tells Garfield how much should be added to the logical unit in order to get the connection identifier. By default, OFFSET is 0. OFFSET should be specified when GKS_IDENTIFIER is used, OFFSET can be specified together with TYPE but this is not recommended. 3 NAME The name of the file that should receive graphics output. By default, GARFIELD.METAFILE. NAME can be used both with TYPE and with GKS_IDENTIFIER. 2 /OLD Calls the previous official release of Garfield. 2 /PRO Calls the current release of Garfield. 2 /NEW Calls the version of Garfield that will be released at the next program library update cycle. This version is subject to modification up to the date of release. 2 /EXP Calls the author's private version. This version changes frequently and deliberate mistakes are sometimes introduced in this version for testing purposes. You're urged to contact the author if you wish to use this version. 2 /ATC_GKS Calls the version of Garfield that is linked with ATC GKS. The executable is not available at CERN. This qualifier is mutually exclusive with /DEC_GKS, /GTS_GRAL, /GKS and /HIGZ. 2 /DEC_GKS Calls the version of Garfield that is linked with Dec GKS. The executable is not available at CERN. This qualifier is mutually exclusive with /ATC_GKS, /GTS_GRAL, /GKS and /HIGZ. 2 /GKS Calls the version of Garfield that uses GTS-GRAL/GKS for its graphics. This module can currently not be kept up to date since the graphics libaries were not made available for the current system and compiler release on Alpha. This qualifier is mutually exclusive with /ATC_GKS, /DEC_GKS and /HIGZ. 2 /GTS_GRAL Calls the version of Garfield that uses GTS-GRAL/GKS for its graphics. This module can currently not be kept up to date since the graphics libaries were not made available for the current system and compiler release on Alpha. This qualifier is mutually exclusive with /ATC_GKS, /DEC_GKS and /HIGZ. 2 /HIGZ Calls the version of Garfield that uses X11 via HIGZ for its graphics output. There is some loss of functionality in comparison with the GKS version. This interface should be considered as a temporary solution for workstation users until the PHIGS version is ready. This qualifier is mutually exclusive with /ATC_GKS, /DEC_GKS, /GTS_GRAL and /GKS. 2 Author Garfield has mainly been written by Rob Veenhof, important contributions by G.A. Erskine, retired DD division CERN, and Carlo Mekenkamp are acknowledged. The data for the various gasses have been provided by users (references in the subroutine headers). The Magboltz program is written and maintained by Steve Biagi, the interface between Garfield and Magboltz has been written by Georg Viehhauser. The interface with HIGZ has been provided by Zhengyong Feng (University of Washington, Seattle, USA). Garfield was developed for the HELIOS (NA34) collaboration at CERN and was first used for the design and calibration of the main drift chambers in that experiment. Since then the program has been used by many other collaborations. The author welcomes comments of the users. No program of this kind can do precisely what the user expect, which is why Garfield has in the 10 years of its existence constantly been extended. Please contact the author at an early stage in case of questions, doubts etc. The author can be reached on the following addresses: VEENHOF@CERNVM (CERN IBM) VXCERN::VEENHOF (DECnet, CERN central Vaxes) 2 Conditions_for_use Garfield, Magboltz and Heed are distributed by the CERN program library according to the general CERN program library guidelines. Garfield, Magboltz and Heed are made available to you under the condition that these programs shall be used only for scientific purposes. These programs and associated files shall not be sold or otherwise made available to third parties without the consent of their authors. The manual and other parts of the documentation shall not be copied, reproduced etc other than for private use. The authors appreciate receiving a copy of any note, internal or published, for which Garfield, Magboltz and Heed have been used. The use of these programs and their auxilliary files is free of charge for work in the context of the scientific programme of CERN. 2 Documentation An extensive printed manual exists which contains information about the program, instructions for compilation, input format, background of the model etc. It can be obtained from the CERN program library, from the author or from the person responsible locally for the program. The manual is also available via WWW on: http://consult.cern.ch/writeup/garfield Inside the program you can type HELP (or ?) at almost any time. The help facility gives detailed information about the instructions with examples. The same information can be consulted via WWW at: http://consult.cern.ch/writeup/garfield/help 2 LSE_and_Garfield This feature has been withdrawn from version 4 onwards because of lack of interest. The LSE file has not been updated since version 2. 2 Limitations Garfield is not suited for applications involving: * Truely 3-dimensional structures, Dielectrics used to be outside the scope of Garfield, but can now be handled through an interface with finite element programs such as Maxwell. Garfield is not very good at the following: * Simulating many, complex shaped electrodes, * Thick wires where dipole and quadrupole terms play a role, Until recently, electron pulses were not computed, now they are. The two limitations are not fundamental and they can be lifted if there is interest.