Title: SIMbes User's Manual (under constant change, no need to print out) By: LiCG@hpws7.ihep.ac.cn Date: Mar-15-1999 Audience: BES members Purpose: guidance to general users on how to run GENbes, SIMbes and XSIMbes Related document: SIMbes Programmer's Reference (for SIMbes programmers and advanced-level users) Disclaimer: data produced by the current version of SIMbes should not be used in physics analysis(such as in thesis and publications) until further notice. The purpose of this release: (1) to get users' feedbacks on the user-interface of the program (is it user-friendly? is it runable at all?); (2) to uncover hidden bugs in the program; (3) to let users conduct comprehensive tests on the program; (4) to let users carry out detector study and develop/improve the BES software. In summary, it is users' responsibility and within users' capability to help improve and perfect GENbes-SIMbes(and DRUNK). We the programmers will be happy to offer technical support. SIMBES-GENBES package has been installed on IHEP's HPUX machines: hpws[2-7], pony[1-2] and hptc[3-4] PC Linux machines: beslx01, mclx DEC Alpha OSF machine: alpha02 (for installation procedure, see SIMbes Programmer's Reference ) ------------------------------------------------------------------------ Table of Contents * 1. What is SIMbes? and GENbes? * 2. How to Run GENbes * 3. How to Run SIMbes and XSIMbes * 4. How to Run GENbes|SIMbes|DRUNK as piped jobs * 5. More on Data Cards * 6. Why GENbes-SIMbes, while we have SOBER? * 7. Questions and Complaints * Appendix A. Advanced Level SIMbes Usage ------------------------------------------------------------------------ 1. What is SIMbes? and GENbes? Reading guide:before you learn to use SIMbes, it is good to have some general idea about what SIMbes and GENbes do. In short, MC simulation = GENbes followed by SIMbes. SIMbes (SIMulation of the BES detector, pronounced as 'SIM-bes) is a newly developed detector simulation program for the BES-I and BES-II detectors. It does basically the same job as SOBER has long been doing for you. However, SIMbes is GEANT3.21-based and therefore can simulate more types of physics processes(such as hadronic showers) more reliably. In simple words, SOBER is an old-day program while SIMbes is more in the trend of HEP world's detector simulation programs. Running SIMbes is as simple as running SOBER. However, SIMbes was not designed to mimic SOBER. You'd better accept SIMbes as a completely new program. Any resemblance to SOBER is purely coincidental. While SOBER has integrated the primary event generators and the data reconstruction code(DRUNK) with the detector simulation, SIMbes performs the detector simulation task only. Primary event generation is the task of another program GENbes(pronounced as 'GEN-bes). Event reconstruction work remains to be, unfortunately, task of DRUNK. You need to first run GENbes to generate events of a given type (such as dimuons, Bhabha), with the results saved in a disk file. Then you run SIMbes to complete the simulation, again with the results saved in a disk file. Finally you run DRUNK to reconstruct these events. (an expensive alternative is to run genbes-simbes-drunk as a chain of jobs via piped i/o files, see Technical note below). We have sound reasons to make GENbes, SIMbes and DRUNK 3 separate and independent jobs, but will not detail the reasons in this short manual (see references). Technical note: a chained job of GENbes-SIMbes-DRUNK is possible with Unix tools of pipe making (mknod) and data copying (dd). However, this requires redesign of the event writing/reading code (C programs beswrite.c besreadg.c, besopenf.c besclosef.c). This has already been done (see section4). Technical note: In SOBER, all event generators get linked to form the executable .sobx. In GENbes, only the event generator actually used (and the subprograms referenced by it) will be linked to the executable. This is obviously a more reasonable and less troublesome way. ------------------------------------------------------------------------ 2. How to Run GENbes Reading guide: all first time users should read this section. Running GENbes-SIMbes is as simple as running SOBER, or even simpler and less error-prone. However, GENbes-SIMbes was not designed to mimic SOBER. You'd better accept SIMbes as a completely new program. Any resemblance to SOBER is purely coincidental. Usage of GENbes-SIMbes is different from usage of SOBER. Major differences are: 1. genbes/simbes has no command-line options for general users (except -help, and one argument for experts to add/use their own code). Technical note: while it is convenient to have command-line options for frequently-executed-fast-commands (such as those Unix shell commands), it is perhaps simpler and safer to use auxiliary setup files to define and pass the parameters for rarely-executed-slow-commands. 2. instead of a single .sobcard file, genbes needs 2 auxiliary files: 'genbes.user' to be sourced by the genbes shell command, and 'genbes.cards' to be read in by the Fortran program. Technical note: don't mix different animals. 3. instead of a single .sobcard file, simbes needs 2 auxiliary files: 'simbes.user' to be sourced by the simbes shell command, and 'simbes.cards' to be read in by the Fortran program. Technical note: don't mix different animals. 4. instead of a single .sobcard file, simbes groups all cards into several card files, general users only need 'simbes.cards' which consists of less than 10 cards. Technical note: HIERARCHY is a recurrent theme in SIMbes. 5. in genbes/simbes, order of cards in cardfiles is arbitrary, each keyname should appear only once. In contrast, some SOBER cards are order-critical, and can appear repeatedly. Technical note: SOBER cards are combination of data cards and control(command) cards. genbes/simbes cards are purely data cards. 6. the random number seeds are automatically selected and saved by the program without user intervention. the program is designed so that it'll pick up the right seed if the job is submitted again with a different event range, or to resume an aborted job at the last event for further debugging. for genbes, a seed consists of 25 integers. for simbes, a seed consists of 27 integers(2 used by Geant3). 7. instead of a single .soblog file, genbesi/simbes each has 3 logfiles: .genlog .simlog summary information .genmess .simmess long screen message .generr .simerr for debugging purpose .genseed_ .simseed_ seed vector for the event whose = .genseed_0 .simseed_0 seed vector for the last event of the job The basic idea is to allow separation based on differences in logical/expertise/experience, and to make the usage very simple(!) and meet practical needs(no fancy and rarely used features). GENBES is merely a driver program which serves as a bridge between users and event generators. Underlying event generators are still those SOBER event generators. So much for philosophy. Here is the usage: type following to get help, and follow the printed directions genbes -h Technical note: the idea or ideal is that users need to read this manual one time only, and then get help by command-line option -help Warning: In principle, the interface between an event generator and the driver program(GENbes or SOBER) should be standardized. That is, all event generators must have the same interface. A typical SOBER event generator requires a _ipar card(MPARAM) and a _rpar card(XPARAM), and phase space generators such as 'howl' needs a few more cards to define event topology (in GENbes, event topology definition is reduced to a single card 'gen_topology'). However, some generators require additional cards. Since some (or many?) SOBER event generators were so thoughtfully designed and documented that it requires both extraordinarily high IQs and EQs to find out what cards and what COMMON blocks a generator requires, and the meanings of each item in a card. we leave it to the users to inform GENbes programmers when problems are encountered with a generator. If we find a generator problematic, we'll remove it from the GENbes (so that the users cannot use it) and restore it until the generator is repaired by experts. For usage of phase space generators such as 'howl', see 5. More on Data Cards ------------------------------------------------------------------------ 3. How to Run SIMbes and XSIMbes Reading guide:all first time users should read this section. type following to get help, and follow the printed directions simbes -h or: xsimbes -h or: dsimbes -h Technical note: the idea or ideal is that users need to read this manual one time only, and then get help by command-line option -help (3) XSIMbes has a KUIP interface (like PAW's user interface) you need to learn some commands by reading GEANT3 manual or get online help once inside XSIMbes Unfortunately, we cannot help much to reduce the complexity of the interactive GEANT3's usage. $BESSROOT/exam/xsimbes.kumac intends to be an introductory example. Note: XSIMbes does not have a counterpart in SOBER. SOBER users may not be able to appreciate the power of XSIMbes at first sight. If you spend some time learning and using XSIMbes, you will surely begin to love this great visual-learning-tool. For example, how far can a 0.3 GeV muon/pion go in the detector? What's the fate of an antiproton in the detector? How big a circle a 0.2 GeV e- traces? XSIMbes is also a great visual debugging tool for the code developers. Geometry errors(wrong shape, size, etc.) would show up so obviously. Note: XSIMbes is currently available on HP and LINUX, but has runtime problem(relating to shared library) on IHEP's ALPHA machine. Now you may find genbes-simbes jobs crash or aborted more often than SOBER jobs. The reasons are: (1) not suprisingly, it takes time and extensive use to expose and fix bugs in genbes/simbes; (2) while SOBER's philosophy is to get around problems quietly, GENbes and SIMbes's philosophy is "never compromise". ------------------------------------------------------------------------ Reading guide:with above information, you can already run GENbes and SIMbes. The following review is only for the sake of completeness of the manual. Job Input Files GENbes: (1) users at all levels: 'genbes.user' --- user's setup 'genbes.cards' --- run data cards (2) for experts to add/use their own code: 'link_genbes.user' --- user's(code developer's) setup 'f.genbes' --- list of the fortran codes to compile 'c.genbes' --- list of the C codes to compile SIMbes: (1) users at all levels: 'simbes.user' --- user's setup (the input GENbes event file is specified here) 'simbes.cards' --- run data cards (2) for experts to add/use their own code: 'link_simbes.user' --- user's(code developer's) setup 'f.simbes' --- list of the fortran code to compile 'c.simbes' --- list of the C code to compile (3) experts may use their own data cards: 'kine.cards' --- to define test events and beam size etc. 'dbg.cards' --- debug settings 'geom_bes2.cards' --- BES-II geometry data 'digi_bes2.cards' --- BES-II digitization data 'geant.cards' --- GEANT3-defined cards With help of the explanatory comment lines in the cardfiles, you can master the usage of the few cards in 'simbes.cards' quickly. The optional cardfiles which give more controls to the user are for more experienced users(users at expert and master levels). ------------------------------------------------------------------------ Job Output Files GENbes: jobname.evt: the event data jobname.genlog: job summary jobname.genmess: lengthy and messy screen messages jobname.generr: for debug purpose jobname.genhbk: contains an event ntuple jobname.genseed_ seed vector for the event whose = jobname.genseed_0 seed vector for the last event of the job SIMbes: jobname.raw: the raw data jobname.simlog: job summary jobname.simmess: lengthy and messy screen messages jobname.simerr: for debug purpose jobname.simhbk: histogram for debug purpose jobname.simseed_ seed vector for the event whose = jobname.simseed_0 seed vector for the last event of the job Note: .evt, .raw, ,genhbk, .simhbk are binary data files. However, they can be regarded as machine-independent data. You can send any of these binary data files to another platform and they can still be digested by subsequent jobs such as simbes, drunk, paw. In addition, genbes and simbes commands ensure that the right executable will be executed even if the machine is in a hetero-cluster (e.g., IHEP's pony1-pony2-pony3 cluster consists of 2 HPUX and 1 Linux machines). Ntuple in 'jobname.genhbk': (1) each track has an entry; (2) nv,nt,nson are artificially signed: nv=abs(nv) for the 1st track of an event, -abs(nv) otherwise; nt=abs(nt) for the 1st track of an event, -abs(nt) otherwise; nson=abs(nson) for the 1st son of an vertex, -abs(nson) otherwise; then, you may, for example, use nt > 0 as per event cut (same as t=1 cut) use nson > 0 as per vertex cut e.g. nt/pl 10.seed nt > 0 nt/pl 10.sqrt(x**2+y**2) nson > 0 (3) vend = 0 for a final state track, otherwise an intermediate state track; (4) ec,pc,cosc,phic are in mother vertex's frame. for most generators this is the same as lab frame. but for a few generators, resonance vertice are included, then tracks out of resonance vertex is in moving vertex frame. ******************************************************** * NTUPLE ID= 10 ENTRIES= 50 GenBES tracks ******************************************************** * Var numb * Name * Lower * Upper * remark ******************************************************** * 1 * evt * .100000E+01 * .100000E+02 * event# * 2 * seed * .322358E+09 * .201821E+10 * random seed * 3 * wt1 * .100000E+01 * .100000E+01 * phasespace weight * 4 * wt2 * .368321E+00 * .107835E+01 * event weight * 5 * nv * -.200000E+01 * .200000E+01 * # of vertices * 6 * nt * -.500000E+01 * .500000E+01 * # of tracks * 7 * v * .100000E+01 * .200000E+01 * mother vertex# * 8 * nson * -.300000E+01 * .300000E+01 * # of tracks out of v * 9 * vmas * .893703E+00 * .309700E+01 * v's mass * 10 * x * .000000E+00 * .000000E+00 * v's x(cm) * 11 * y * .000000E+00 * .000000E+00 * v's y(cm) * 12 * z * .000000E+00 * .000000E+00 * v's z(cm) * 13 * t * .100000E+01 * .500000E+01 * track# * 14 * tmom * .000000E+00 * .100000E+01 * mother track# * 15 * vend * .000000E+00 * .200000E+01 * terminal v# * 16 * pid * .100000E+01 * .260000E+02 * SOBER pid * 17 * q * -.100000E+01 * .100000E+01 * charge * 18 * m * .000000E+00 * .958124E+00 * mass(GeV) * 19 * ec * .446852E+00 * .111757E+01 * E in mother frame * 20 * pc * .105658E+00 * .575453E+00 * |p| in mom frame * 21 * cosc * -.990659E+00 * .965456E+00 * cos in mom frame * 22 * phic * .658069E+01 * .359501E+03 * phi(deg) in mom frame ******************************************************** ------------------------------------------------------------------------ 4. How to Run GEBbes|SIMbes|DRUNK as piped jobs If you don't want to save the generated primary events and simulated events on disk files, but want to reconstruct them directly, you can try a job chain "genbesP; simbesP; drunk ..." with following steps: (1) copy besopenf.c,besclosef.c besreadg.c, beswrite.c from $BESSROOT/rec/src to your drunk job dir (2) include this line in your .drkcard: /*LINK besopenf besclosef besreadg beswrite (3) run the chained jobs: genbesP; simbesP; drunk -v100 -r rec; (the name "genbesP" is reminiscent of "genbes|", and "simbesP" of "simbes|") What's going on is like this: genbesP writes the generated events to a pipe (FIFO) instead of a normal data file; simbesP reads in the events from the pipe; simbesP writes the simulated events(rawdata) to another pipe, drunk reads in the events from the pipe. It is also possible to run a partial chain, e.g.: genbesP; simbes; or simbesP; drunk -v100 -r rec; Hint: since genbes is many times faster than simbes and drunk, and drunk is usually much faster than simbes, it is usually a waste of system resources to run these three jobs as a chain. This chain is necessary only for very big jobs, e.g., to simulate and reconstruct 200,000 events. Even in this case, you'd better try a small scale genbes, simbes, drunk normal (not chained) job to test your cards and programs, and then start a big chained job. ------------------------------------------------------------------------ 5. More on Data Cards Reading guide:new users do not need to read this section. Refer to this section only after you have some exprience with running GENbes and SIMbes. GENbes and SIMbes's card-reading functionality is based on CERNLIB's FFREAD package, with two improvements: (1) key name can be longer than 4-characters, upto 16-characters; (2) a line beginning with any of the following 4 characters is regarded as a comment line: *, !, #, / Conventions: '#' starts a comment line; '*' also starts a comment line '!' de-activates(comments out) a data card (1) the order of cards is non-essential; (2) keyname's case(uppercase,lowercase) is non-essential; (3) a card can be one line or multiple lines with at least one space in the beginning of a continuation line; (4) if several cards have identical keyname, only the last card takes effect; 4.1 GENbes cards GenBES cards are few and simple. They are all in one cardfile. GeneratorName_ipar card serves same purpose as SOBER's MPARAM card GeneratorName_rpar card serves same purpose as SOBER's XPARAM card Since all *_ipar cards are actually aliases of mparam card, and all *_rpar cards are actually aliases of xparam card, therefore, you must comment out all un-used *_ipar and *_rpar cards. i.e., 'genbes.cards' should contain no more than one _ipar card and no more than one _rpar card. event_range 1001 2000 1000 events will be generated with event_id from 1001 to 2000 gen_topology: this card defines event topology for phase space generator such as 'howl'. In SOBER, event topology is defined via combination of 7 types of control cards(chrg_trks, neut_trks, gamma, autodecay, decay, resonance, spin_prt). Usage of these 7 cards is unreasonably confusing and unsafe. SOBER codes parsing these cards are also unreasonably complex. GENbes redesigned the interface to the phase space generators. example: the following card defines process e+e- --> eta' p pbar |--> gamma gamma * number of particle lines gen_topology 5 * line# ifrom pid charge: integer 0, +/-1, +/-2 30 0 26 0 10 0 6 +1 21 0 6 -1 4 30 1 0 5 30 1 0 Note on gen_topology card: 1. each line defines one particle(track), except that the 1st line tells the total number of lines(tracks) in the process; 2. line# serves as label, any non-zero number is ok; 3. ifrom = mother track's line#; ifrom = 0 means this line comes from e+e-; 4. SOBER pid alone is not sufficient to identify a particle, need (pid,charge) pair to identify a particle; assign_mass, assign_spin, assign_parity, assign_life, assign_width these cards allow users to (re)define these properties of particles. Note on assign_* cards: 1. each card can assign values to a list of particles; 2. the 1st line tells how many particles will be redefined by this card; 3. each following line is of the form In GENbes and SIMbes, you should never let a given card(e.g., assign_mass) to appear more than once. 4.2 SIMbes cards Usage of 'event_range' cards: event_range 1001 2000 SIMbes will process the event if the event_id falls between 1001-2000. An event is skipped if its event_id is out of range. Note: (1) in the input .evt file, the event with id = 1001 may or may not be the first event in the file; (2) the event with id = 2000 may or may not be the last event in the .evt file, but the simbes job will stop after processing this event. (3) SIMbes's philosophy is to supply a minimal set of user cards. users need a little experience and inventiveness in using the cards. e.g., 'nevent' card is not supplied, but one can easily ge t around it using 'event_range' card only. GENbes assigns each event an ID. GENbes card 'event_range' specifies the ID range. SIMbes card 'event_range' selects the ID range. ------------------------------------------------------------------------ 6. Why GENbes-SIMbes, while we have SOBER? Reading guide:this section is a philosophy reading for sober-minded users. Pragmatic users do not need to read this section. It does not hurt to have an alternative simulation program for sure. However, this is not the purpose of SIMbes, the development of which has taken 3 man-years labor. And many SOBER users may not be so curious about learning how to use a new program *if* this new program does exacly the *same* job as the old one. Now there are several arguments in favor of using SIMbes: (1) SIMbes does much better simulation job than SOBER. SOBER does not actually simulate the shower development caused by pions, kaons, protons because its shower code is EGS4 which simulates electromagnetic interactions only, not the nuclear(strong) interactions. That is to say, SOBER does not actually simulate the shower counters(BSC and ESC) and the muon detector(MUO). (2) SIMbes can display a single event in the detector interactively. SOBER or DRUNK can display the detector and *reconstructed* tracks, but not the *generated* tracks and hits. SIMbes has 2 main programs("simbes" and "xsimbes"), one is for batch production mode, the other for interactive graphical display mode. One can link these 2 main programs to the same set of libraries to get the 2 executables(simbes.exe and xsimbes.exe) without need of changing any SIMbes subroutines. That's to say, SIMbes gets the interactive and graphical feature free, at no cost to the BES programmers' labor. As you can imagine, to add an event displaying ability alone may take more time, skills and risks than writing the whole SIMbes program. As for the value of XSIMbes (the interactive SIMbes), one can hardly overestimate it. With XSIMbes, -- you visualize a Monte Carlo event as it is being generated; -- you acquire intuitive understanding of the particles and their interation with the detector materials; -- needless to say, XSIMbes is a very powerful debugging tool for the code developers (remember how Single Event Display has helped you in the Run Control Room?). If we think XSIMbes as a HPUX workstation with its graphical user interface, then SOBER reminds us a VT100 terminal. (3) SIMbes needs much lesser code maintenance work than SOBER. This is because SIMbes is a GEANT3.21 application, which means we can leave to CERNLIB/GEANT3 the most sophisticated, theoretically or technically challenging coding tasks, as well as the most tedious database maintenance chores. In contrast, SOBER is home-made. SOBER was derived from the old MARK3's simulation program which was written amid 1970s(the early days of the microprocessors and personal computers). The computer world has undergone tremendous changes since then. Today, BES is equipped with advanced models of HPUX workstations. As for software environment, CERNLIB has become HEP's de facto standard library in the past decade. In particular, CERNLIB offers a package called GEANT which undertakes major part of the detector simulation work. SIMbes is based on GEANT3.21, which is the latest released version of GEANT (Object-Oriented GEANT4 is still in development stage). In terms of GEANT3 version number, SIMbes is more advanced than many other existing experiments' simulation programs. (4) SIMbes is easier to be upgraded, even to a C++ program. At the time of SimBES code development, FORTRAN begins to give way to C++ in the HEP world. GEANT3 will soon be superseded by GEANT4 which is written in C++ and "Object-Oriented". While SimBES is written in FORTRAN77 and is based on GEANT3.21 to be on the safe side, it is well-structured to make the transition to GEANT4 and C++ smooth. For one thing, SIMbes does not define COMMON blocks for communication between SIMbes subroutines. Technical note: now that ROOT, an object-oriented(written in C++) framework developed by the author of PAW and Geant3 and several others, is available, our plan is to transform GENbes-SIMbes to C++ programs in the ROOT framework. The design of GENbes-SIMbes makes this task simple and straightforward. (5) SIMbes is well maintained. (if all the previous reasons do not convince you, this one should) SOBER is(, was and will be) maintained only perfunctorily, because it is intrinsically and practically unmaintainable. While SOBER is at most partly and vaguely understood by few living souls in the BES collaboration, we can announce loudly and proudly: SIMbes is fully understood -- no blackbox on the SIMbes part(we don't worry so much about the GEANT3 part, which has been used and tested by our comrades worldwide). ------------------------------------------------------------------------ Acknowledgments We appreciate the constant support of the IHEP Computing Center and the Data Group of Division 1: SIMbes project has never encountered any problem from the machine and software environment(GEANT3.21 and CERN libraries). ------------------------------------------------------------------------ GENbes and SIMbes are designed and constructed principally by: C.G. Li Division 1 IHEP, Beijing Contributing code developers: J.C. Chen (ESC signal production) B.S. Cheng (VTX and BSC signal production) H.M. Liu (MUO signal production) L. Zhang (BTOF and ETOF signal production) Division 1 IHEP, Beijing ------------------------------------------------------------------------ 7. Questions and Complaints SIMbes is definitely superior to SOBER at least in one respect: questions and complaints will be listened to and answered in a timely manner. Please contact one of the following code maintenance staff: licg@hpws7.ihep.ac.cn (MDC, GENbes, user interface) chenjc@hpws7.ihep.ac.cn (ESC) chengbs@hpws7.ihep.ac.cn (VC, BSC) liuhm@hpws7.ihep.ac.cn (MUO) lzhang@hpws7.ihep.ac.cn (TOF) or: besphy-l@slac.stanfor.edu (mail list for discussion on SIMBES issues) ------------------------------------------------------------------------ Appendix A. Advanced Level SIMbes Usage SIMbes is designed to be highly flexible. For example, all following can be achieved by changing data cards: subdetectors can be turned On, Off(no signal readout), or Out(taken out); card: geom card in 'run.cards' pre-digitization GEANT hit data can be dumped to disk file; cards: run_phase card in 'run.cards' out_type card in 'run.cards' fast simulation starts with the saved hits data (good for digitization code and parameter study); cards: run_phase card in 'run.cards' the magnetic field can be turned on and off in the whole detector cards: geom_bfield card in 'geom.cards' the magnetic field can be turned on and off in each component; cards: tmed_* cards in 'geom.cards' much of the geometrical and material makeup of the detector can be redefined(you may need a good understanding of GEANT3 to do this); cards: certain relevant cards in 'geom.cards' use card-defined test particles instead of physical events by event generators; cards: kine card in 'kine.cards' kine_part card in 'kine.cards' use card-defined constants instead of data from calibration files; cards: relevant cards in 'digi.cards'