Title: SIMbes Programmer's Reference (under constant change, no need to print out) By: LiCG@hpws7.ihep.ac.cn Date: Jul-01-1998 Audience: GENbes-SIMbes code developers and advanced-level users Purpose: to explain technical essence of SIMbes and GENbes Related document: SIMbes User's Manual (for general users of GENbes-SIMbes) ------------------------------------------------------------------------ Table of Contents * 1. File Organization and Installation Procedure * 2. Design Considerations * 3. Code Reference Structure * 4. Data Access Methods * 5. Error Handling and Report * 6. Data Cards * 7. Code Maintenance Utilities * 8. Geometry Code * 9. Digitization Code * 10. Trouble Shooting * Appendix A. Add Your Own Generator * Appendix B. Write Your Own Run Script ------------------------------------------------------------------------ 1. File Organization and Installation Procedure 1.1 File organizaion $BESSROOT/ collection of BESS source codes, docs, libs and tools. subdirectories under $BESSROOT/ directory: (Note: $BESSROOT is different from $BESROOT) bin/ collection of general user commands: genbes, simbes, etc. const2/ files of monte carlo BES-II constants: wire survey, dead channel, realization doc/ collection of BESS documentations exam/ examples of auxiliary files needed by genbes-simbes jobs gen/ collection of GENBES source codes lib/ archived GENBES and SIMBES object code(slibgenbes.a etc) sim/ collection of SIMBES source codes site/ site-dependent settings and system's default settings tmp/ temporary working area for library compilation etc util/ collection of commands and tools for code develop and maintenance -- versions: (1) version number = v102nn, nn = 00, 01, ..., 99 (2) current version files in general do not carry version number, while retired files do. e.g., suppose current version = v10203, then sim/src/bccell.F is the current version sim/src/bccell.F.02 is retired v10202 version (3) libs: libgenbes10203.a, libsimbes10201.a, etc lib*.a always carry the version number libgenbes.a is linked to current version's libgenbes libsimbes.a is linked to current version's libsimbes (4) in 'genbes.user' and 'simbes.user' files, user can optionally specify which version lib to link to. -- updating BESS package is not maintained by CODEMAN. Therefore developing work on different sites cannot be synchronized automatically. At present, IHEP's $BESSPRIME (on hp) is the only authentic location for BESS distribution. bess.tar.gz v10200 package updatenn.tar.gz v102nn changes(nn = 01,02,..,99) 1.2 Installation Procedure: Note: in the future CODEMAN will handle it? (1) download install_bess command example (2) edit 'install_bess.example', and name it as 'install_bess' put the file in any directory, better be unrelated to your $local_BESSROOT, e.g. ~/ (3) chmod u+x install_bess, then execute ./install_bess (4) after installation, you still need to insert following 2 lines somewhere in the csh setup file: setenv BESSROOT if ( -e $BESSROOT/site/bess.cshrc ) source $BESSROOT/site/bess.cshrc ------------------------------------------------------------------------ 2. Design Considerations Note: the success of GENbes-SIMbes was based on the design philosophy (software engineering ideas) described in this section. Any modification of the GENbes-SIMbes codes must not violate the basic philosophy described in this section. Apart from GEANTization, the major goals of GENbes-SIMbes are: (1) programmer-friendly: to make the program maintainable and reliable; (2) user-friendly: to make the program a flexible tool. The main strategies are: 1. GENbes generates primary events; SIMbes passes the primary events through the detector simulation; The only link between GENbes and SIMbes is the primary event data file(and definition of the event data structure). 2. A design feature of GEANT is the separation of GEOM-TRAK-DIGI stages. SIMbes respects this feature. Within SIMbes, detector definition(GEOM), GEANT3 tracking(TRAK) and signal production(DIGI) are 3 distinct stages(phases). User may opt to save each phase's output to a disk file, and later executing SIMbes on some stages(phases) only. This feature demands that the code of the 3 stages(phases) are properly isolated(decoupled) from each other. 3. GENbes and SIMbes code reference structure must be hierarchical. The purpose/role/reason is to separate high-level tasks from low-level implementation details. 3.1 a function usually calls no more than 5 major(nontrivial) functions 3.2 details such as data structure/format etc. must be hidden from higher level functions. 3.3 de-centralized initialization procedure; 4. SIMbes code structure must be modularized(each subdetector must stand alone and can be turned on and off by run control cards). 4.1 the names of similar modules must share similar pattern. e.g. dccell(), bccell(), mucell() 5. Global data(COMMON block) should be avoided. All-local-data policy makes it extremely difficult to pass data between functions, and hence requires very thoughtful design of the code reference structure(often a well-designed function does not need to exchange a lot of data with other functions). 6. Subscript indexing should be avoided. This requires extensive use of structured(formatted) data(make intelligent use of EQUIVALENCE). 7. Many of the detector constants are defined in the data cards which can be read in at run-time(therefore can be changed before each run). This makes SIMbes a powerful tool for the detector study and sysmatic error analysis. The central ideas are: (1) hierachical (separation of layers/levels); (1.1) "built-in", decentralized and cascaded-down initialization procedures; (1.2) avoid subscript indexing(hiding implementation details); (2) less coupling between different tasks, module, layers, subprograms; (2.1) make any remaining couplings(data flows) visible; (3) flexible (unlike the real detector, the simulated detector should be "rubber-like": re-scalable, variable); ------------------------------------------------------------------------ 3. Code Reference Structure 3.1 GENbes code structure genbes --- the main program inigen --- to initialize the program event generation loop: evtgen --- to generate an event evtfil --- to fill the event ntuple evtout --- to write out the event endgen --- to terminate the job ------------------------------------------------------------------------ 3.2 SIMbes code structure The code reference structure is basically what's defined by GEANT3. GEANT3's grun_(and its decendents) calls some user subroutines gu* (such as gukine_, gustep_). "user" means whoever uses GEANT3 and in our case means SIMbes. All gu* subroutines have a default/dummy version supplied by GEANT3. Note: in GENbes and SIMbes source code, all CERNLIB/GEANT3 global symbols(subprogram names and COMMON block names) have postpended underscores(as explained in section 3.3). simbes --- the main program for noninteractive batch mode uginit --- to initialize the program grun_ --- this is GEANT3's event loop top level steering subroutine uglast --- to terminate the job The interfacing code to grun_ are: gukine_ --- read a primary event into the GEANT3 data structure gustep_ --- save hit data(after a tracking step) in GEANT3 data structure gudigi_ --- top level steering routine for digitizing an event which involves retrieving hit data from the GEANT3 data structure and digitizing(produce signals from hits) the event guout_ --- write out the event In uginit: cardin --- read in the data card file 'run.cards' ugeom --- defines the detector geometry gukine_0 --- init gukine_ gustep_0 --- init gustep_ gudigi_0 --- init gudigi_ guout_0 --- init guout_ Note that initialization calls are organized in a hierarchical way. e.g., init of dccell is done through the following path: simbes.uginit.gudigi_0.ugdigi_0.dcdigi_0.dccell_0 uginit simply does not know how many functions need initialization. ------------------------------------------------------------------------ 3.3 tricks in compile and link 3.3.1 make GENbes-SIMbes global symbols invisible(inaccessible) to functions/subprograms in the external(lower-level, underlying) libraries GEANT3.21 and other CERN library source code have been compiled with +ppu (postpending underscore) compiler option. GENbes and SIMbes source code are compiled without +ppu option. The consequences are: (1) GEANT3 and CERNLIB subroutines/functions must be called with a postpending underscore in SIMbes source code; (2) SIMbes function names are invisible to GEANT3 and CERNLIB subroutines/functions, unless named with a postpending underscore. This way, we've made SIMbes functions(without postpending underscore) sit above and invisible(not callable) by GEANT3 and CERNLIB subroutines/functions. It is in general desirable that code in upper layers can reference code in lower layers but not vise verse. Then programmers of upper layers code don't need to worry the global name conflict with lower level code in the library. 3.3.2 use C preprocessor directives Use #ifdef , #endif to enclose a section of the C or Fortran source code which can be included or excluded(ignored) by the C preprocessor (for our purpose, the task of the preprocessor is to extract the source code to be compiled). The way GENbes-SIMbes use the flags: #ifdef vdebug: to enclose debugging lines ------------------------------------------------------------------------ 4. Data Access Methods 4.1 scope and duration of data Correct coding and understanding of GENbes-SIMbes program require a good understanding of the difference between "automatic" data and "static" data, between local data and global data. Upon execution of a program, the executable code and data are stored in the internal memories(RAMs) which can be accessed by the CPU quickly and efficiently. The internal memories used by the program are devided into 3 regions: stacks, statics, and free store. stacks: a temporary storage used by the function/subroutine currently invoked. Data on the stack are "automatic"(not saved after exiting the current function/subroutine) and "local"(not accessible by other functions/subroutines); static region: a region to store the executable code and "saved" data. Data in this region are "static" in the sense that they will not be changed "automatically/unintentionally", but can be changed by the (value assigning) statements in the code. However, the names of the data in this region can be either "local" or "global". free store: what's left unoccupied between stacks and the static regions. Now we see that (1) "duration" is determined by the location of the storage: all data on stacks are "automatic"; all data on static region are "static". (2) relation between "scope" and storage region is not so simple. Data on "stacks" can only be "automatic"; "global" data must be stored on "static region"; But the data stored on "staic region" can also be "local static". Therefore, there are 3 types of data in Fortran77: 1. "local automatic" 2. "local static" 3. "global" (can only be "global static") Summary: In Fortran77, there are 2 types of "scope" and 2 types of "duration": scope: (1) local (2) global (names of SUBROUTINE, FUNCTION,COMMON) duration: (1) automatic (2) static (data declared by SAVE, DATA, COMMON) Note: platform peculiarites: 1. EQUIVALENCE data are automatic on DEC Alpha but are static on HPUX , PC Linux(g77 compiler) 2. HPUX linker require that for any given COMMON block, at least one data item must be initialized by DATA statement, otherwise the linker would search libraries for any object that does this init. In case of SOBER COMMON blocks, for example, if a genbes code refers /eventt_/ but none of genbes codes initialize any data in /eventt_/, the linker would get SOBER's init.o linked, and thus make the executable size increased by 2MB (from 0.7MB to 2.7MB). Note: by setting a compiler option, all data can be stored in "static" region, and therefore made static(as SOBER and DRUNK did). However, we consider this a bad and dangerous practice. Reasons: (1) stack is speedy and economical for storing local data; (2) mistakes in "automatic" data(like array subscripts outbound) usually cause the program crash, while the same mistakes in "static" data may pass unnoticed! It is always the most dangerous to have hidden bugs. For offline programs, we'd rather have the program crach on even trivial bugs. 4.2 multi-ENTRY Realization of the GENbes-SIMbes design goals depends crucially on two instruments in the standard Fortran77: ENTRY and EQUIVALENCE. Data privatization is an uncommon feature of SIMbes(as a Fortran program). In Fortran77, ENTRY and static data (by DATA or SAVE or EQUIVALENCE) make the data encapsulation possible. Multiple ENTRY of the same subroutine/function can share a set of "local static" data. e.g., function dccell.F has 3 entries: integer function dccell(nhit,ilay,iwire,icell,vhits,kt,kq) entry dccell_keys() entry dccell_0() At initilization stage, dccell_keys() is firstly called to declare some card keys; then dccell_0(), the initialization entry, is called; In the event loop, dccell(nhit,ilay,iwire,icell,vhits,kt,kq) is called to digitize a MDC cell. Note that from the view point of code maintenance, distributed/built-in initialization (realized by multi-ENTRY) has great advantages over the centralized initialization(as in SOBER's init.f). This is actually demanded by "hierarchical" code structure. 4.3 formatting array with EQUIVALENCE address-by-name instead of address-by-index is a very effective safety measure in GENbes-SIMbes design SIMbes avoids using array subscript indexing. Elements of different types(Integer, Real, Character) can be put in the same array, and referenced by name(and must be referenced by names to avoid error). The key technique is EQUIVALENCE. e.g., include file 'trk.bus' defines array trk() and its elements. integer n_trk parameter (n_trk=13) integer trk(n_trk) c integer t_nw integer t_i integer t_v0 integer t_vend integer t_id integer t_q real t_m real t_life real t_width real t_p(4) equivalence (t_nw, trk(1)) ! number of words = 13 equivalence (t_i, trk(2)) ! track# equivalence (t_v0, trk(3)) ! vertex# birth equivalence (t_vend, trk(4)) ! vertex# death equivalence (t_id, trk(5)) ! pid equivalence (t_q, trk(6)) ! charge equivalence (t_m, trk(7)) ! mass equivalence (t_life, trk(8)) ! lifetime in ??? equivalence (t_width,trk(9)) ! width in GeV equivalence (t_p, trk(10)) ! 4-mom c Why cannot we use Structure(like "struct" in C) and Record(instance of Structure) in SIMbes? Within SIMbes, it is fine to use Structure & Record. However, only arrays can be used to communicate with GEANT3 and FFREAD (CERNLIB's free-format card define/read unilities). In the standard Fortran77, there are 2 ways to format an array: (i) use COMMON block (ii) use EQUIVALENCE as we did in SIMbes Since SIMbes doe snot use COMMON block, the only choice left is EQUIVALENCE. ------------------------------------------------------------------------ 5. Error Handling and Report Error handling is part of the code development environment/facilities. It should be designed and coded before coding of the major part of the program. An error reporting routine should report: (1) who is screaming (the caller) (2) what's happened (error message text) (3) where did it happen (location in the source code) (4) how bad (type/severity/nature of the error) (5) what action was taken (warned, skip the event, terminate the job) ermess(), erskip(), erterm() are the error reporting/handling tools in GENbes and SIMbes. In most cases, ermess/erterm decision is made by the function which has discovered/trapped the error, and upper level callers will only ermess the error. In SIMbes, event skip and job termination is done by GEANT3, which examines the data flags "ieotri" and "ieorun" to decide whetehr to skip the event and terminate the job. erterm() and erskip() set these flags in GEANT3's COMMON block. In GENbes, the flags are examined in the main program genbes. Errors are printed in .genlog, .genmess, .generr, .simlog, .simmess, .simerr files. In these files, %NOTE begins a notice (not an error) %WARN begins a waring message (perhaps a minor error) %SKIP begins an event-skipping message %ABORT begins a job-termination message e.g.: Message: %WARN evtout -> 1 Run 0 Event 1 Loc 1 Case UnSelect exception v_i= 1 v_nson= 0 ison= 4 Explanation: function evtout() sends a warning message in run#=0 event#=1 location=1 in the source code, case=unselected message text = "exception v_i= 1 v_nson= 0 ison= 4" In general, error messsages look mysterious to non-experts, but provides enough debugging information to the expert when s/he reads into the source code. .simlog(.genlog) is the short summary log file for a SIMbes(GENbes) job; .simmess(.genmess) is the lengthy message file for a SIMbes(GENbes) job; .simerr(.generr) is the error file for debugging purpose. Using of 3 instead of 1 message file has proved to be a very good practice. ------------------------------------------------------------------------ 6. Data Cards Usually, a detector simulation program stores the detector geometry constants in the code as COMMON block data (values assigned by DATA statements), and reads in the calibration constants from disk files. SIMbes reads in all detector geometry data from card files (on disk) and may optionally read in digitization constants either from the (Monte Carlo) calibration data files or from the data cards(the latter option requires redefinition of SIMbes-DRUNK interface and raw data structures in the future). This design is based on the observation that geometry data can be treated as stable and uniform for repeated cells and therefore can be defined by a small number of data cards, while calibration data may vary cell by cell and may be run period depednent hence need to be stored in a data file. This design makes SIMbes very flexible -- user can change the detector by editing the data cards, no need to re-compile and link the program. However, taking advantage of this feature requires a good understanding of the GEANT3 method of detector definition and SIMbes's digitization code. ------------------------------------------------------------------------ 7. Code Maintenance Utilities Investment in code developing tools is always worthy of the cost. show_moms: list mothers of a subroutine/function in SIMbes,SOBER,DRUNK show_sons: list sons of a subroutine/function in SIMbes,SOBER,DRUNK show_card: explain the meaning of a SIMbes data card, where is it defined and who reference the card show_data: who reference a global data in SOBER, DRUNK just type the commands and read the help message. ------------------------------------------------------------------------ 8. Geometry Code Note: Geometry code is "GEANT intensive". You need to read GEANT3.21 Manual to understand the geometry code and design. 8.1 general concepts of GEANT3 geometry The task of geometry code is to describe the detector geometry structure and material composition. In a detector simulation program, a detector consists of a number of "lowest level" volumes. In each "lowest level" volume, the material(medium) is considered to be homogeneous. A lowest level volume is defined by a set of attributes: (1) geometrical attributes such as: shape, size (2) content attributes: material(medium) ID (3) tracking properties: desired precision of simulation such as step length. (note tracking properties are not intrinsic to the material, but defined for computing technical purposes) In GEANT3, material definition is separated from the volume definition. Material is defined by a set of attributes: (1) composition of the medium, if it is a mixture of other materials; (2) charge density of electrons and nucleons. (3) radiation length and nuclear interactive length etc. The detector is a pile of such defined lowest level volumes with filling medium. GEANT3 geometry package has following roles: (1) it provides some predefined geometrical shapes; (2) it provides some predefined materials; (3) it provides tools(subroutines) to let users set the scales and medium contents of a predefined shape; (4) it provides tools(subroutines) to let users position a daughter volume in a mother volume, or divide a mother volume into repeated cells; A GEANT3 described detector is typically a geometry tree with several layers. Unlike SOBER, GEANT3's geometry scheme (1) is separated from tracking so that GEANT3 tracking is applicable to any geometry, not limited to a specific geometrical configuration; (2) reduces user's work to miminal in geometry definition; (3) provides a structured geometrical configuration where volumes are related to each other logically. We can see that hierachy and decoupling are golden rules and frequently resorted strategy in software engineering. 8.2 GEANT3 HITS data structure A track (particle) leaves trace in the sensitive cells of the detector. These footprints of the track are called "hits". In GEANT3 terminology, a "hit" is a user-defined vector of user-selected attributes of the track, such as (x,y,z), time-of-flight, energy deposition. At "tracking" stage, hits can be saved in GEANT3's HITS data structure. Later, at "digitization" stage, hits can be retrieved from the HITS data structure and be "digitized" into signals such as pulse height and time. In the real detector, hits(primary energy depositon in the medium) are amplified(typically by high voltage electrical field) and converted to electronic signals. These low energy processes(order of 1 eV) cannot be genuinely simulated in a simulation program due to economial reasons. Simulatrion stops typically at order of 1 MeV to 1 keV. Event energy is typically above 1 GeV. The cpu time per event is roughly proportional to the ratio of event energy over stop energy. Since hits are related to the sensitive cells, their storage is also related to the cells. The structure of the hit storage is closely related to the structure of the geometry. In fact, the decision of what hits and how the hits be saved interferes with the design of the BES geometry. In SIMbes, some subdetector's geometry structure may look not elegant or not economical at first sight. But when you consider the need of hits storage carefully, you'll understand why. (Note: This undesired and perhaps unexpected coupling between geometry and hits perhaps reflects a design deficiency in GEANT3.) 8.3 SIMbes geometry code structure: ugeom gpart_: defines standard Geant3 particles upart: adds SIMbes-defined particles gmate_: defines standard Geant3 materials umate: adds SIMbes-defined materials if(XX) XXgeom_0: init XXgeom, XX = cd/vc,dc,bt,et,bc,ec,mu b2geom: defines the grandma and 1st level volumes if(XX) XXgeom: defines subdetector XX, XX = cd/vc,dc,bt,et,bc,ec,mu btgeom_pos: position subdetectors into the grandma and 1st level volumes if(XXsensitive) XXsdet: declares sensitive components 8.4 Geometry code of each subdetector 8.4.0 some general considerations GEANT3 requires that a grandma volume(the root of the tree) must be defined, and all lowest level (homogeneous) volumes must be defined. However, it is left to the user of GEANT3 what intermediate level volumes to insert in between. We have following principles to guide SIMbes's geometry design: (1) the search should better be hierachical; It is faster to locate a person if the person's country, province, city, street and building are known, than to locate the person among all populace on Earth. Therefore some auxiliary volumes are inserted between the lowest level volumes and the grandma volume. (2) the search should better be 1-dimensional; GEANT3 tracking is slow in 2-3 dimensional tracking, and is not so good at reducing a 2,3-dim problem into 1-dim problems. Therefore, users of GEANT3 need to provide some help. We divide the grandma volume radially into some first level tube shaped volumes, then divide the radial tubes along z-axis if necessary. (3) economical in storage; In general, positioning daughter volumes in a mother volume takes more storage space and more tracking time. Wherever applicable, division should be considered first. Using generic shape(free size) is another economical way. In addition, we aim at (4) rescalable and flexible; A simulated detector should have more free parameters than a real detector. When you can "perturb" a detector, you understand it better. In SIMbes, the lowest-level volume is "lowest" in 2 senses: (1) mediumwise, it is homogeneous; (2) for readout purpose, it corresponds to no more than 1 readout volume. For example, the lowest volume in DC is not layer, but a phi-cell. This is superior to SOBER in that digitization algorithm would be much simpler. In the following we explain general design considerations of each subdetector's geometry code. A lot of detailed explanations are made in the footnotes in the source code(XXgeom.F), and should be referenced. In creating a subdetector's geometry code, we first define the data cards "geom_*.key", then complete _key() and _0() entries, and then define volumes and the struture. 8.4.1 VCGEOM VC consists of an inner wall(a radial shell), outer walls(a radial shell and two endcaps) and the gas volume in which 640 "straw tubes" are positioned in 4 stereo layers (layers 5..8) and 8 axial layers. A straw tube is represented by a gas-filled tube of zero thickness. The stereo layers of straw tubes present the major difficulty in geometry description of VC. There is no economical way in GEANT3 to put stereo tubes in the VC volume. Therefore, we use the brutal force method: to position straw tubes one by one in the VC volume. For axial layers, we could have divided the layer into phi-cells, and put a straw tube in each phi-cell. But this would add complexity of the code and does not save much CPU(since the CPU is mainly consumed by simulation of the dense materials). VCTi = a straw tube in layer i, i=1..12 GVTC = gas volume of VC IVTC = inner wall of VC WVTC = VC GVTC and IVTC are positioned inside WVTC copies of VCTi are positioned inside GVTC The VC geometry is defined by 56 parameters in 2 cards(see 'inc/geom_vc.key' and 'inc/geom_vccel.key'). 8.4.2 DCGEOM DC consists of 5 stereo layers(1,3,5,7,9) and 5 axial layers, each layer is divided into a number of phi-cells. We should note that geometry defition is for the purpose of GEANT3 tracking, not directly for digitization, therefore, some digitization-related properties such as the electrical field and positions of the wires are irrelevant and not represented in the DC geometry. The envelope of a stereo layer is hyperboloid shaped. Note this is different from the case of VC stereo layers where the envelope is irrelevant(this difference is subtle but must be recognized). An axial layer is represented by a "TUBE". A stereo layer is represented by the difference of 2 "HYPE" volumes(this makes the dcgeom code much more complicated). It is a shame that GEANT3 cannot represent a stereo layer simply by a single "HYPE" volume. This makes the DC geometry the most challeging task. There's no way to divide phi-cell "stereoly". Therefore, we have to be content with "straight" phi-division, and leave it to the digitization code to correct the phi-cell number. In SOBER, tracking does not see phi-cells, and it is left to the digitization code to determine which phi-cells were hit by a track. SIMbes defines phi-cell into the DC geometry so that GEANT3 tracking sees the phi-cells, and the digitization algorithm becomes much simpler and straightforward. In general, we prefer to leave minimal work to the digitization code(code programmers), at cost of a little extra work on GEANT3 side. GMDC = DC gas volume WMDC = GMDC + aluminum endplates OMDC = outer aluminum wall of DC (OMDC is longer than WMDC) Definition of layers and cells is explained in 'src/dcgeom.F'. DC geometry is defined by 51 parameters in 2 cards(see 'inc/geom_mdc.key', 'inc/geom_dccel.key') 8.4.3 BTGEOM BT geometry is the simplest among the BES subdetectors. BT consists of 48 identical scintillators. A scintillator is represented by a trapezoid(shape TRD1). STOF = first level tube shaped volume BTFC = a phi division cell of STOF BTSC = a trapezoidal scintillator positioned inside BTFC BT geometry is defined by 7 parameters in 1 card(see 'inc/geom_btof.key'). These 7 parameters are so selected that they can be changed easily and safely, to rescale the BTOF. Even the number of scintillators can be changed easily. In graphical debugging(using XSIMbes), it helps if the number of cells could be reduced to below 10, for example. 8.4.4 ETGEOM ET geometry is similar to BTGEOM. ET consists of 2 endcaps and each endcaps consists of 24 identical scintillators. A scintillator is represented by a trapezoid(shape TRD1). WETF = one of the endcap TOF ETFC = a phi division cell of WETF ETSC = a trapezoidal scintillator positioned inside ETFC ET geometry is defined by 9 parameters in 2 card(see 'inc/geom_etof.key', 'inc/geom_zetf.key'). These 9 parameters are so selected that they can be changed easily and safely, to rescale the ETOF. Even the number of scintillators can be changed easily. In graphical debugging(using XSIMbes), it helps if the number of cells could be reduced to below 10, for example. 8.4.5 BCGEOM BC geometry is defined by 17 parameters in 4 cards(see 'inc/geom_bsci.key', 'inc/geom_bscv.key', 'inc/geom_bclay.key', 'inc/geom_bccel.key'). 8.4.5 ECGEOM EC geometry is very complicated, next only to MU geometry. EC geometry is defined by 22 parameters in 7 cards(see 'inc/geom_zesc.key', 'inc/geom_esc.key', 'inc/geom_ecsqs.key', 'inc/geom_ecpb.key', 'inc/geom_ecnz.key', 'inc/geom_ecnx.key', 'inc/geom_ecrx.key'). 8.4.7 MUGEOM MU geometry is the most complicated among the BES subdetectors. MU geometry is defined by 101 parameters in 4 cards(see 'inc/geom_mufe.key', 'inc/geom_mucel.key', 'inc/geom_mulay.key', 'inc/geom_mugap.key'). ------------------------------------------------------------------------ 9. Digitization Code The digitization code has 3 tasks: (1) to retrieve the hits from GEANT3's HITS data structure; (2) to digitize the hits into readout signals; (3) to pack the readout signals into the BES-online raw data format. The first task is GEANT3-technical, the third task is BES-online-technical, and the second task is subdetector-physics-technical. It is advantageous to separate different expertise in different functions. Therefore, we have XXdigi() ( XX=VT,DC,BT, etc.) for the first annd the third tasks, and leave the second task to XXcell() functions. There are two things make XXdigi() algorithms complicated: (1) a readout cell may consist of more than one physical cell; (2) there may be more than one hit in the same readout cell. Our strategy is to absorb the algorithmic difficulties into Xdigi(), and let XXcell() programmers concentrate on subdetector physics. Since XXdigi() is rather complicated in programming technique, we made all XXdigi() functions very similar. We started with bcdigi() (BC readout scheme is rather comlicated) and adapted it to simpler cases such as dcdigi(). ------------------------------------------------------------------------ 10. Trouble Shooting The job may (1) terminate normally, i.e., finished successfully; or (2) terminate abnormally, i.e., fatal error was caught by the program; or (3) crash, i.e., fatal error was caught by the system's fortran runner. In trouble locating, you rely on following information and tools, before resorting to brutal force debugging method: (1) the job.simlog and job.simmess, job.simerr files (2) change the settings of following cards geom run_phase dbg_list out_type out_rawsub out_mcmsub Once you have mastered the usage of these cards in testing and debugging, you'll appreciate the design of SIMBES more. ------------------------------------------------------------------------ Acknowledgments We appreciate the constant support of the IHEP Computing Center and the Data Group of Division 1: SIMbes project has never encountered problems from the machine and software environment(GEANT3.21 and CERN libraries). ------------------------------------------------------------------------ GENbes and SIMbes software is designed, constructed and marketed principally by: C.G. Li Division 1 IHEP, Beijing Contributing code developers are: J.C. Chen (ESC signal formation) B.S. Cheng (VTX and BSC signal formation) C.G. Li (MDC signal formation) H.M. Liu (MUO signal formation) L. Zhang (BTOF and ETOF signal formation) Division 1 IHEP, Beijing Questions? Complaints? Please contact one of the following code maintenance staff: licg@hpws7.ihep.ac.cn (General, MDC, GENbes) 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) ------------------------------------------------------------------------ Appendix A. Add Your Own Generator You may want to call a generator which is unknown to GENbes/SOBER, or you want to call your private version of a generator that's known to GENbes/SOBER. GENbes treats these 2 cases the same way as it would treat a normal generator. However, if you have provided your library (which is an archive file of your generator's object codes), link_genbes (called from genbes command) would search your lib before it searches the standard SOBER's lib. Suppose your library file is 'libmygen.a'(for genbes), and 'libmygen_dbg.a' is its debug version(for dgenbes), then include the following 2 lines in your 'link_genbes.user': setenv MyLib mygen setenv MyLib_dbg mygen_dbg so that link_genbes would search "libmygen.a" before searching SOBER v100's "libbes_v100.a" for the generator object codes. It's your job to prepare libmygen.a (and libmygen_dbg.a for dgenbes) You should compile them with "+ppu" option: f77 -c +T +ppu ... mygen.f Then archive all objects: rm libmygen.a; ar r libmygen.a *.o Your lib should be in the same dir as genbes.user, link_genbes.user etc ------------------------------------------------------------------------ Appendix B. Write Your Own Run Script We have designed user interface for beginners, so that a beginner can submit a SIMbes job by: simbes We do not intend to provide a command interface that will satisfy all users needs. An all-purpose shell script tends to be lengthy and messy. Advanced users may want to write their own run scripts. To survive in Unix environment, you should be able to write your own shell scripts. SIMbes commands are currently written in csh scripts. However, you may as well write your own in more powerful ksh scripts. Hint: for beginners, the easiest way is not to adapt the existing genbes/simbes scripts, but to write your own scripts from scratch! Here we explain what genbes, simbes and xsimbes command do. You will see the essential tasks of the command scripts are very simple: make all needed i/o files available to the Fortran executable. 1. Ingredients of genbes command (1) make following files available to the executable Fortran program ("filename" is the internal name recognised by the Fortran program) filename I/O remark ----------------------------------------------------- run.cards I program run control cards evt.dat O data of generated events, as input to simbes hbk.dat O histograms and ntuples for data validation ftn6 O lengthy and messy screen