# $Id$ # Flugg tag $Name$ ==================================================================== ==================================================================== READ-ME-FLUGG - Sara Vanini - June 2000 Upgrade to Geant4 3.1, I. Hrivnacova, 30 May 2001 (FLUGG documentation: ATL-SOFT-98-039 and ATL-SOFT-99-004.) ==================================================================== ==================================================================== ==================================================================== = 1. Flugg Installation = ==================================================================== 1.1 Supported computers and operating systems -------------------------------------------------------------------- FLUGG is supported under the following operating systems: - Flavors of Unix (from vendors HP, DEC) - Linux on PC with g++ (egcs compiler) Currently, this is the set of flavors which can be associated with the environment variable $G4SYSTEM to identify the system architecture and compiler used: UNIX - HP-UX v.10.20, aCC v.1.23 G4SYSTEM: HP-aCC DEC-OSF/1 v.4.0, cxx 6.1 G4SYSTEM: DEC-cxx Linux - Linux RedHat 6.1, g++ egcs 1.1.2 G4SYSTEM: Linux-g++ 1.2 Required software ------------------------------------------------------------------- To run FLUGG, the following software must be properly installed in your computing environment: - C++ compiler (compiler from Unix vendor, g++ or Visual C++ for Windows systems); - CLHEP library (see CLHEP reference guide http://wwwinfo. cern.ch/asd/lhc++/clhep/manual/RefGuide/index.html); - Native STL or ObjectSpace STL (see http://www.objectspace.com/) - GNU Make (note: g++ preprocessing is used to build file dependencies) is also used and a UNIX shell; - FLUGG toolkit; - FLUKA libraries; 1.3 FLUGG environment -------------------------------------------------------------------- Before proceeding with the installation, you need to define some key environment variables in your user environment, in order to specify where all software components are placed and to set some compilation options: FLUKA path to fluka binary files; FORLIB path to the fortran library; FLUPRO path to fluka program FLUKAOBJ_PATH path to fluka objects; FLUKAOBJ name of fluka objects (user's routines, ecc.); FLUGGINSTALL path where the FLUGG toolkit tree is installed; G4SYSTEM set to one of the flavors listed in the above section to specify the kind of architecture and compiler used; G4GEOMETRY_DEBUG if set the additional debug information is printed in the log file (default = unset) G4LIB_BUILD_SHARED if set shared libraries are built, static ones otherwise (default = unset) CLHEP_BASE_DIR: path to the CLHEP installation OSPACE_BASE_DIR: path to the ObjectSpace STL installation (in case ObjectSpace STL implementation is used in place of the system's native STL). 1.4 How to make G4 libraries -------------------------------------------------------------------- At this point, do the following to start building the compilation and installation of the kernel libraries. You can choose to build libraries in one of two ways, according to the needs and system resources. From $FLUGGINSTALL/source: 1.gmake global This will make global libraries, one for each major category. 2.gmake This will make one library for each "leaf" category (maximum library granularity) and produce automatically a map of library use and dependencies. The standard build procedure assumes global libraries if they exist. Advantages of using approach 2. can be noticed mainly concerning library and program build speed, which in some cases can be improved also of a factor 2 or 3 compared to the "global library" approach. Using the "granular library" approach a fairly big number of "leaf" libraries is produced, dependencies and linking list are however evaluated and generated automatically on the fly. The top-level GNUmakefile in $FLUGGINSTALL/source parses the dependency files of FLUGG and produces libname.map in $G4LIB. libname.map is produced by the tool liblist, whose source code is in $FLUGGINSTALL/config. When building a binary application the script binmake.gmk in $FLUGGINSTALL/config will parse the user's dependency files and use libname.map to determine through liblist the required libraries to add to the linking list. Only the required libraries will be loaded at link time. 1.5 FLUKA libraries -------------------------------------------------------------------- For FLUKA libraries and FLUKA data files, pemf file, etc, you could take a look at FLUKA manual. At this point, you'll be ready to start building your first FLUGG application. ==================================================================== = 2. FluGG - Fluka + Geant4 Geometry for Simulation in HEP = ==================================================================== 2.1 How to build a FLUGG example -------------------------------------------------------------------- You can create a FLUGG example in the directory: $(FLUGGINSTALL)/examples/fluggEx/emptyEx a)GEOMETRY The detector definition requires the representation of its geometrical elements, their materials and electronics properties, together with user defined properties. FLUGG geometrical representation of detector elements requires implementing the following G4 classes: - Detector Construction (named "MyDetectorConstruction"); - Detector Parameterization (optional); - Magnetic Field Construction (optional); You must define these classes in include directory and their implementation in src of the above directory. (see http://wwwinfo.cern.ch/ asd/geant4/G4UsersDocuments/UsersGuides/ForApplicationDeveloper/html/ index.html for details on how to write a G4 geometry). As regards geometry construction, remember that replicas and parameterized volumes are handled as fluka lattice-volumes, so boundaries between them are not seen during tracking time. Different placements of identical physical volumes, instead, correspond to different fluka-regions (boundaries are seen!). As regards magnetic field construction: 1) Fluka needs flagged region for magnetic field. So it is imperative to flag logical volumes (in Detector Construction file) where magnetic field is present for FLUGG simulation (in GEANT4 this isn't necessary, you can define only magnetic field too). How volumes can be flagged: 1.a) with flag in G4LogicalVolume constructor: logicBox = new G4LogicalVolume(solidBox,BoxMaterial, "Box",fieldMgr,0,0); 1.b) with member function: logicBigBox->SetFieldManager(fieldMgr,true); *true flag implies that the field is extended to all volume daughters (for field in all detector set this flag for world volume!). 2) If field is defined with G4UniformMgnField (so it's uniform) the field value is written in fluka card MGNFIELD (in flukaMat.inp file). If field is defined with a user-implemented function, MAGFLD wrapper gives the local value as fluka calls it run time. b)FLUGG ENVIRONMENT VARIABLES Define environment variables described in section 1.3. c)FLUGG EXECUTABLE In the directory: $(FLUGGINSTALL)/examples/fluggEx/emptyEx, run "gmake" (or "gmake clean" and then "gmake" to recompile all files). Gmake creates the executable ($(FLUGGINSTALL)/bin/Linux-g++/mainFLUGG) compiling FLUGG geometry classes, linking G4 geometry libraries and fluka libraries (libflukahp.a). d)FLUKA INPUT Now, to run FLUGG, you need fluka-stile input file. You can see FLUKA manual for details, and input and pemf file examples in /flugg/ examples/fluka. Remember that GEOBEGIN-GEOEND card is dummy (you have to put no lines between GEOBEGIN and GEOEND, geometry input comes from G4 classes!). As regards material specification: in GEANT4 toolkit, materials and material-volume assignments are specified in geometry input classes, in the detector constructor file. When FLUGG initializes the geometry, material information is read from GEANT4 detector description, and translated into FLUKA-formatted input cards. So a first dummy run must be executed; the newly created file containing GEANT4 material specifications and volume-material assignments (flukaMat.inp) must be included into the FLUKA input file where additional properties can still be defined. Other useful information, like FLUGG geometry volume names and indexes (together with repetition numbers for replicated or parameterized volumes!) are dump in Volumes_index.inp. Now you are ready to run mainFLUGG (see rfluka script in /flugg/ examples/fluka). 2.2 Examples module -------------------------------------------------------------------- This module collects a set of user examples aimed to demonstrate to a user how to make correct use of the FLUGG toolkit by implementing those user-classes which a Geant4 user is supposed to customize in order to define his/her own detector geometry setup. This set of examples covers some possible general use-cases for actual detector simulation for HEP. AlAuAl - series of slab of different elements (Al, Au, Al), which total thickness is of the order of the electron range; - multiple scattering at boundaries (handle delicate situations such as grazing angles, backscattering, deflections at boundaries); Fluka input files: alaual.inp, wa_50m.pemf BiasEx - 500 MeV protons on a thick Cu target: the generated neutrons propagate in a concrete shield; - fluka biasing techniques are applied to achieve variance reduction; Fluka input files: Bias.inp, wa_50m.pemf MagSphereNotRep - test-geometry with spheres and tubs; - tracking in magnetic field; Fluka input files: MagSphereNotRep.inp, t36.pemf T36flugg - Test-36 em-hadronic calorimeter; - Full "ordinary" processes; - no magnetic field; Fluka input files: T36.inp, t36.pemf Appendix A. FLUKA input --> FLUGG input ******************************************************** When transposing a fluka input in a flugg input you need to: a) Update the following fluka cards substituting fluka region indexes with G4 geometry volume indexes: (in parenthesis the WHAT() with region numbers): ASSIGNMAT (2,3,4) BEAMPOS (6) BIASING (4,5,6) DETECT (6; contin.card:2-6) EMF-BIAS (4,5,6) EMFCUT (4,5,6) EMFRAY (2,3,4) EXPTRANS (3,4,5) GEOBEGIN/END no WHAT exept COMBINAT; throw away everything between GEOBEGIN/END GLOBAL (1) LOW-BIAS (4,5,6) LOW-DOWN (4,5,6) RESNUCLEI (5,6) STEPSIZE (3,4,5) TIMECUT (5,6) USRBDX (4,5) USRBIN (4,5,6; contin.card:1,2,3,4,5,6) USRCOLL (4) USRTRACK (4) USRYIELD (4,5) WW-FACTO (4,5,6) b)integrate the following material cards with information: DELTARAY, EMF-BIAS, EMF-CUT, EMF-FIX, EMF-FLUO, EVXTEST, FLUKAFIX, LAM-BIAS, LANDAU, LOW-MAT, MAT-PROP, MULSOPT, OPT-PROP, PAIRBREM, PHOTONUC; and in MAPA and PEMF file, which contain detailed information about materials. When comparing fluka and FLUGG runs, REMEMBER to: 1) check that coordinate system is the same in fluka geometry and in GEANT4 geometry; if it is not, update position and beam direction. 2) check how events are the scored! Appendix B. GEANT4 example --> FLUGG example: **************************************************************** 0) Copy /src and /include geant4 examples directories in emptyEx/ 1) Delete all classes exept: - Detector Construction; - Detector Parameterization; - Magnetic Field Construction; 2) Delete corresponding "#include ..." lines in Detector Construction source file and variables definitions in the constructor, and corresponding class declarations and variable declaration in Detector Construction include file. 2b) Delete #include "G4RunManager.hh" and lines where RunManager is invoked. 3) Delete Detector messenger, initialization and destruction, delete code lines where Sensitive Detector is set (be aware of memory leaks!). 4) Delete code lines where parameterization of processes for fast simulation is set (and visualization of ghost volumes). Delete commands for interactive definition of the calorimeter Appendix C. How to update FLUGG with new Geant4 releases **************************************************************** For updating FLUGG with new Geant4 releases the following operations are required: 1) from flugg/source: gmake clean_all to remove the previous installation; 2) unzip and untar Geant4 release; 3) set environment variable for paths to Geant4 (G4INSTALL) and Flugg (FLUGGINSTALL) 4) run update_source.sh script This will replace files placed in include and src sub-directories of the following directories: geant4/source/geometry ---> flugg/source/geometry geant4/source/graphics_reps ---> flugg/source/graphics_reps geant4/source/material ---> flugg/source/material geant4/source/global ---> flugg/source/global geant4/source/intercoms ---> flugg/source/intercoms The Geant4 makefiles are modified for Flugg; old Flugg makefiles are kept and renamed to GNUmakefile.flugg and kept. 5) now you must add "UpdateNavigatorHistory" member function to G4Navigator class; insert the following declaration in "flugg/source/geometry/volumes/include/G4Navigator.hh" file: // flugg member function: reinitialization of navigator history with // secondary particle history banked on fluka side void UpdateNavigatorHistory(const G4NavigationHistory* newNavHistory); 6) And append the following definition to "flugg/source/geometry/volumes/src/G4Navigator.cc" file: void G4Navigator::UpdateNavigatorHistory(const G4NavigationHistory* newNavHistory) { ResetStackAndState(); fHistory = *newNavHistory; SetupHierarchy(); } 7) run update_config.sh This will replace makefiles placed in config directory with new ones from Geant4 modified for Flugg; old makefiles are kept and renamed (by adding .flugg extension). !!! binmake.gmk has to be updated by hands. In case no major modifications were done in config in new Geant4 release the old binmake.gmk may be used without modofications.