+--------------------------------------------------------------------+ | Event generator for processes: | | 1. pe->pe+gamma including radiative corrections to lepton current | | 2. pe->pel+l-, l=e,mu | +--------------------------------------------------------------------+ Content of this document: ========================= I. Program information II. Compilation III. Integration IV. Event generation V. Script options list I. Program information ====================== 1. Review note with the analysis of the processes will be published soon. Program web page: http://desy.de/~vmakar/bh/. Matrix elements for all processes are available at: http://desy.de/~vmakar/bh/doc/. 2. Considered processes: * pe->pe+gamma with the photon emitted along the electron beam axis. The one-loop radiative corrections to lepton current are included; * pe->pe l^{+}l^{-} with l=e,mu. This process affect the electron tagger only. 3. Two external packages are used: * LoopTools ver.2.5 by T.Hahn; * QD by Y.Hida, Xi.S.Li and D.H.Bailey. These external codes are included into the source code archive for simplicity only. One must refer these packages whenever using the generator. The references are: * T. Hahn, Nucl.Phys.Proc.Suppl. {\bf 89}(2000)231-236; * Y.Hida, Xi.S.Li, D.H.Bailey, Tech. Report LBNL-46996(2000). 4. Program structure: ./: The root folder contains compilation script 'bhmake' and this 'ReadMe.txt' file. The other files here including 'Makefile' are used internally by 'bhmake'. ./src: Source files. ./bin: Executable files path. ./run: Program execution examples. Contains sub-folders for every program execution step. The scripts used for splitting/merging of parallel runs are located in sub-folders. See Secs. III-IV for further details. External packages: ./LoopTools-2.5: The exact copy of the LoopTools package (built Feb'2010); ./qd-2.3.8: The exact copy of the QD package. 5. The main result of the generator is the event file(s) created. The generation-time analysis is also available via. modifying the generation procedure. See 'GenProcMain()' procedure in 'BH_main.cpp' file for event generation cycle: > for(i=0; ((i CVM4Vec* pFinE=NULL; CVM4Vec* pGamma=NULL; CVM4Vec* pGamma2=NULL; CVM4Vec* pFinE2=NULL; CVM4Vec* pFinEm=NULL; > g.GetParticleRefs(pGamma,pGamma2,pFinE,pFinE2,pFinEm); One can follow the example histogram filling there (replacing old histograms by ROOT ones). 6. System requirements: * 48h-long batch service with 2Gb RAM machines; * 'ifort'-compiler for compilation of LoopTools with 16-byte precision; * Up to 4Gb of disc space for parallel V-term integration and event generation procedures. The program was originally tested with DESY Zeuthen batch service. 7. Execution time. Integration (strictly depends on the precision required): * less than 1hr for Born process integration; * 20 parallel runs x 12hrs for loop and soft bremsstrahlung correction integration. * 30hrs for hard bremsstrahlung correction integration. * 16-24hrs for pe->peee and pe->pe2mu processes integration. Events generation: * 10^6 events per ~2 hours. Parallel generation of events is available. II. Compilation =============== 1. Note: No 'make' to be called directly. 2. First make: > ./bhmake -all 16 Result: creates 'test16' executable in '/bin' directory. Notes: '-all' means compilation of external packages. * Required at first compilation or if the code location was changed; * Makes 'clean' for all sub projects; * The LoopTools's configuration script is substituted with 'LT_configure25' file, that saves library path used by LoopTools into '\LoopTools-X\LDFLAGS.var' file. The saved path is used further for linking. '16' means 16-byte floating point numbers. QD's 'dd_real' type is used in generator and ifort's 'REAL*16' is used in LoopTools. The value '32' ('qd_real' type) is required if non-default matrix element versions are used. 3. Further makes (recompilation after any of the "./src/xxx.cpp(h)" files is changed): > make clean 'make clean' command is required if the header files are changed. (The compiler checks modification time of '.cpp' files only!) This command doesn't clear LoopTools or QD compilations. Thus, no new '-all'-compilation is required. > ./bhmake -bh 16 '-bh' means compilation of './src'-files only. The LoopTools and QD packages 4. Create additional executable used for faster Born process calculation: > make clean The command is required if '8/16/32' parameter is changed since last compilation. > ./bhmake -bh 8 Result: creates 'test8' executable in './bin' directory. Use '-bh' here if LT and QD libraries were compiled earlier. III. Integration ================ The program requires preliminary integration of the processes. It takes about 1-day when the calculations are parallel. The ready-to-use generator contains large integration grid files (~500Gb) and may requested at author. 1. The program reads 'bh.ini' in local directory. The ini-file structure: comments #KEYNAME VALUE comments #KEYNAME VALUE comments #KEYNAME VALUE comments comments Every key starts from '#'-symbol and is followed by the value after the space-symbol. All other statements in ini-file are ignored. 2. The example runs for integration of the processes are located in './run/i_XXX/'-folders. The result of runs (except large grid files) are located in './run/i_XXX_res/'-folders. Every project contain 'run..' script with the following content: > #!/bin/csh -f > cd /afs/...PATH.../bh/920/i_Born/ > ./../../bin/test16-q > run.log > gzip bh_grid.Born.genl > gzip bh_grid.RHard.genl > gzip bh_grid.VCorr.genl > gzip bh_grid.Peee.genl > gzip bh_grid.eMuMu.genl Important: For simplicity the generator program is not installed and there is no common variable with program path set. Therefore one should modify the first line above inserting the correct path to working directory. In the second line the relative path to executable file is used. One should modify this line if the directory structure is changed. The last lines are used to minimize the disk space for the integration grid files created. 3. The sequence of statements is used for integration depends on the batch service command syntax. Here are the commands used with DESY Zeuthen batch service: > cd ./runs/ > qsub -l h_vmem=500M -l h_cpu=12:00:00 ./i_Born/runB > qsub -l h_vmem=2000M -l h_cpu=48:00:00 ./i_RHard/runR > qsub -l h_vmem=2000M -l h_cpu=48:00:00 ./i_Peee/run3e > qsub -l h_vmem=2000M -l h_cpu=48:00:00 ./i_Pe2mu/run2mu Later, after the Born cross section is calculated, one should copy the Born grid into 'VCorr'-folder and use it for loop correction integration. > cp -r ./i_Born/bh_grid.Born.genl.gz ./i_VCorrOverBorn/ > cd ./i_VCorrOverBorn/ > gzip -d ./bh_grid.Born.genl.gz > mv ./bh_grid.Born.genl ./bh_grid.VCorr.genl > ./bhrun16 > cd .. Important: The 'bhrun16' script is used for starting the parallel execution of 20 (up to 100) batch runs. Every run is executed with the independent set of random numbers. This file must be modified before use: 'bhrun16' contains DESY Zeuthen batch commands and './../../bin/' path to the executable. When all batches are finished one should combine the low-precision loop-integration grids (created in parallel runs) into the single one. Again, one should check the paths used in scripts. > cd ./i_VCorrOverBorn/ > ./run_merge_adv > rm -r ./bh_grid.VCorr.genl > rm -r ./subgrids.tar.gz > cd .. Here we have removed the initial 'seed' grid and internal sub-results. The final loop-correction grid is located at ./i_VCorrOverBorn/merge/bh_grid.VCorr.genl.gz IV. Event generation ==================== 1. The example event generation project is located at ./runs/gen1/ The first step is to copy grid files into the project folder: > cd ./runs/gen1/ > cp -r ./../i_VCorrOverBorn/merge/bh_grid.VCorr.genl.gz . > cp -r ./../i_RHard/bh_grid.RHard.genl.gz . > cp -r ./../i_Peee/bh_grid.Peee.genl.gz . > cp -r ./../i_Pe2mu/bh_grid.eMuMu.genl.gz . Some files may occur uncompressed and thus must be copied without the '.gz'-suffix. Check if the 'VCorr','RHard' and 'Peee' files are successfully copied (The 'eMuMu'-process may be ignored). 2. Next one must adjust the 'bhrun16' script for proper batch commands and executable path (see also Sec.III). The other option is to set the number of events requested. The number of events in single run (in 'bh.ini'): #NEVT 1000000 The number of parallel runs (in 'bhrun16', actual number is 'N+1'): N=19 3. Next start the parallel generation: > ./bhrun16 The '#LOAD 1' parameter in 'bh.ini' declares that previously-created grid files must be used. 4. When all runs are finished, move event files to the single directory: > ./mvevts 5. The events can be combined and analyzed using the script: > ./combine16 The 'sum' sub folder will be created containing the results averaged over all event files. Note: this procedure may take significant time (up to 30 mins). 6. Compress grid files used (or remove them) > ./runzip 7. The event file format: [To be updated!] 8. To see processes info: look for 'Table of processes' block in 'run.log' +------------------------------------------------------------------+ | Table of processes | +------------------------------------------------------------------+ | Born: 72.4722 +/- 0.0597177 mb, share: 0.995749 | Peee: 0.125695 +/- 0.00088998 mb, share: 0.00172702 | RExcl: 0.183735 +/- 0.00142593 mb, share: 0.00252447 +------------------------------------------------------------------+ The errors are declared starting from '[Error]' word. All other information in 'run.log' is useless. V. Script options list ====================== Important: * The syntax is: #KEY value '#KEY' must be at the start of line and separated form the 'value' by space symbol. All other statements are ignored as comments. The order of parameters is arbitrary. * The default values are used if the parameter is missed. * Modify cut/energy and other kinematic parameters simultaneously in all sub-processes. The event generation with 'E_cut=10' but the grid file created for 'E_cut=5' is erroneous. * Use default parameters (i.e. don't use explicit parameter declarations) when possible. Basic options: #EE 27.6 - electron energy (def: 27.6) #EP 920 - proton energy (def: 920.) #NEVT 100000 - number of events to generate (def: 100000) #SAVEEL 0 - save electron/positron records to events file #LOAD 0 - try to load grid file instead of a new integration (def. 0) #DONT_SAVE_EVT - don't create event files to save disk space. #NEVTCL 0 - number of events generated for comparison using the Bethe-Heitler formula. #m_bUsePreviousGrid - used for V-term integration 'over' the previously generated Born-grid. Process selection: 1 or 0 #PROC_BORN #PROC_PEEE [unused! #PROC_RHARD] #PROC_VCORR #PROC_RSOFT -- used currently instead of 'RHARD' and MEANS 'RHARD'. #PROC_REXCL -- for debug only #PROC_MUMU Sub-process (matrix element version) selection: Don't change the default values in examples! #SUBPROC_BORN #SUBPROC_PEEE #SUBPROC_RHARD #SUBPROC_RSOFT #SUBPROC_REXCL #SUBPROC_VCORR #SUBPROC_MUMU Global settings #EgMinIR 0.000001 Soft and Hard bremsstrahlung separator Integration-only settings #PREC 0.003 precision requested #GENOMIN 12 minimal order of the phase space splitting #GENOMAX 200 minimal order of the phase space splitting #DEBUG 1 generate debug output #I_SUBEVTS 1000 - number of events in every cell Integration-step cuts #ICUTEeMIN 3 #ICUTEeMAX 10 #ICUTQMIN 1e-24 #ICUTQMAX 1e+5 #ICUTEMIN 5 integration cut (def. 5) #ICUTEMAX 27.6 integration cut (def. 27.6) Generation-only settings: #EVTKIND 1 (unweighted events) #UPDMAX 0 (update maximal value in cell during the event generation procedure) #m_fMaxSafeFact 2 (use fMax*Factor value instead of 'fMax' for event generation) Generation-step cuts: #GCUTEeMIN #GCUTEeMAX #GCUTEMIN 5 generation cut (def. 5) #GCUTEMAX 27.6 generation cut (def. 27.6) #GCUTTMIN 0 generation cut (def. 0) #GCUTTMAX 0.003 generation cut (def. 0.003) Misc. settings #m_iFixPhotonNo 1 method of fixing of 2-photons double-counting in R-process #m_iAxisSelMode 4 method of next-to-split axis selection #I_ORDERFIRST 20 more events for first 20 cell orders #I_SUBFIRST 4000 number of events if the cell order is <20 The other parameters are used for debug and can be tracked via script parsing routine in 'BH_value.cpp'.