Calculation of new variables needed for Non-id HBT added. (Z. Chajecki)
[u/mrichter/AliRoot.git] / Flugg / documents / README-FLUGG
CommitLineData
8035eb36 1# $Id$
2# Flugg tag $Name$
3
4====================================================================
5====================================================================
6READ-ME-FLUGG - Sara Vanini - June 2000
7Upgrade to Geant4 3.1, I. Hrivnacova, 30 May 2001
8
9(FLUGG documentation: ATL-SOFT-98-039 and ATL-SOFT-99-004.)
10====================================================================
11====================================================================
12
13
14====================================================================
15= 1. Flugg Installation =
16====================================================================
17
181.1 Supported computers and operating systems
19--------------------------------------------------------------------
20FLUGG is supported under the following operating systems:
21
22 - Flavors of Unix (from vendors HP, DEC)
23 - Linux on PC with g++ (egcs compiler)
24
25Currently, this is the set of flavors which can be associated with
26the environment variable $G4SYSTEM to
27identify the system architecture and compiler used:
28
29 UNIX - HP-UX v.10.20, aCC v.1.23 G4SYSTEM: HP-aCC
30 DEC-OSF/1 v.4.0, cxx 6.1 G4SYSTEM: DEC-cxx
31 Linux - Linux RedHat 6.1, g++ egcs 1.1.2 G4SYSTEM: Linux-g++
32
331.2 Required software
34-------------------------------------------------------------------
35To run FLUGG, the following software must be properly installed in
36your computing environment:
37
38 - C++ compiler (compiler from Unix vendor, g++ or Visual C++
39 for Windows systems);
40 - CLHEP library (see CLHEP reference guide http://wwwinfo.
41 cern.ch/asd/lhc++/clhep/manual/RefGuide/index.html);
42 - Native STL or ObjectSpace STL
43 (see http://www.objectspace.com/)
44 - GNU Make (note: g++ preprocessing is used to build file
45 dependencies) is also used and a UNIX shell;
46 - FLUGG toolkit;
47 - FLUKA libraries;
48
491.3 FLUGG environment
50--------------------------------------------------------------------
51Before proceeding with the installation, you need to define some key
52environment variables in your user environment, in order to specify
53where all software components are placed and to set some compilation
54options:
55
56FLUKA path to fluka binary files;
57FORLIB path to the fortran library;
58FLUPRO path to fluka program
59FLUKAOBJ_PATH path to fluka objects;
60FLUKAOBJ name of fluka objects (user's routines, ecc.);
61
62FLUGGINSTALL path where the FLUGG toolkit tree is installed;
63G4SYSTEM set to one of the flavors listed in the above section to
64 specify the kind of architecture and compiler used;
65G4GEOMETRY_DEBUG if set the additional debug information is printed
66 in the log file (default = unset)
67G4LIB_BUILD_SHARED if set shared libraries are built, static ones otherwise
68 (default = unset)
69
70CLHEP_BASE_DIR: path to the CLHEP installation
71OSPACE_BASE_DIR: path to the ObjectSpace STL installation (in case
72 ObjectSpace STL implementation is used in place of the system's
73 native STL).
74
75
761.4 How to make G4 libraries
77--------------------------------------------------------------------
78At this point, do the following to start building the compilation
79and installation of the kernel libraries.
80You can choose to build libraries in one of two ways, according to
81the needs and system resources. From $FLUGGINSTALL/source:
82
83 1.gmake global
84 This will make global libraries, one for each major category.
85 2.gmake
86 This will make one library for each "leaf" category (maximum
87 library granularity) and produce automatically a map
88 of library use and dependencies.
89
90The standard build procedure assumes global libraries if they exist.
91Advantages of using approach 2. can be noticed mainly concerning
92library and program build speed, which in some cases can be improved
93also of a factor 2 or 3 compared to the "global library" approach.
94Using the "granular library" approach a fairly big number of "leaf"
95libraries is produced, dependencies and linking list are however
96evaluated and generated automatically on the fly. The top-level
97GNUmakefile in $FLUGGINSTALL/source parses the dependency files of
98FLUGG and produces libname.map in $G4LIB. libname.map is produced
99by the tool liblist, whose source code is in $FLUGGINSTALL/config.
100When building a binary application the script binmake.gmk in
101$FLUGGINSTALL/config will parse the user's dependency files and use
102libname.map to determine through liblist the required libraries
103to add to the linking list. Only the required libraries will be
104loaded at link time.
105
106
107
1081.5 FLUKA libraries
109--------------------------------------------------------------------
110For FLUKA libraries and FLUKA data files, pemf file, etc, you could
111take a look at FLUKA manual.
112
113At this point, you'll be ready to start building your first
114FLUGG application.
115
116
117====================================================================
118= 2. FluGG - Fluka + Geant4 Geometry for Simulation in HEP =
119====================================================================
120
1212.1 How to build a FLUGG example
122--------------------------------------------------------------------
123You can create a FLUGG example in the directory:
124$(FLUGGINSTALL)/examples/fluggEx/emptyEx
125
126a)GEOMETRY
127The detector definition requires the representation of its geometrical
128elements, their materials and electronics properties, together with
129user defined properties. FLUGG geometrical representation of
130detector elements requires implementing the following G4 classes:
131 - Detector Construction (named "MyDetectorConstruction");
132 - Detector Parameterization (optional);
133 - Magnetic Field Construction (optional);
134
135You must define these classes in include directory and their
136implementation in src of the above directory. (see http://wwwinfo.cern.ch/
137asd/geant4/G4UsersDocuments/UsersGuides/ForApplicationDeveloper/html/
138index.html for details on how to write a G4 geometry).
139
140As regards geometry construction, remember that replicas and
141parameterized volumes are handled as fluka lattice-volumes, so
142boundaries between them are not seen during tracking time.
143Different placements of identical physical volumes, instead,
144correspond to different fluka-regions (boundaries are seen!).
145
146As regards magnetic field construction:
1471) Fluka needs flagged region for magnetic field. So it is
148imperative to flag logical volumes (in Detector Construction
149file) where magnetic field is present for FLUGG simulation
150(in GEANT4 this isn't necessary, you can define only
151magnetic field too).
152
153How volumes can be flagged:
154 1.a) with flag in G4LogicalVolume constructor:
155 logicBox = new G4LogicalVolume(solidBox,BoxMaterial,
156 "Box",fieldMgr,0,0);
157 1.b) with member function:
158 logicBigBox->SetFieldManager(fieldMgr,true);
159 *true flag implies that the field is extended to all
160 volume daughters (for field in all detector set this
161 flag for world volume!).
162
1632) If field is defined with G4UniformMgnField (so it's uniform)
164the field value is written in fluka card MGNFIELD (in flukaMat.inp
165file). If field is defined with a user-implemented function,
166MAGFLD wrapper gives the local value as fluka calls it run time.
167
168
169b)FLUGG ENVIRONMENT VARIABLES
170Define environment variables described in section 1.3.
171
172c)FLUGG EXECUTABLE
173In the directory: $(FLUGGINSTALL)/examples/fluggEx/emptyEx,
174run "gmake" (or "gmake clean" and then "gmake" to recompile all files).
175Gmake creates the executable ($(FLUGGINSTALL)/bin/Linux-g++/mainFLUGG)
176compiling FLUGG geometry classes, linking G4 geometry libraries
177and fluka libraries (libflukahp.a).
178
179d)FLUKA INPUT
180Now, to run FLUGG, you need fluka-stile input file. You can see FLUKA
181manual for details, and input and pemf file examples in /flugg/
182examples/fluka. Remember that GEOBEGIN-GEOEND card is dummy (you
183have to put no lines between GEOBEGIN and GEOEND, geometry input comes
184from G4 classes!). As regards material specification: in GEANT4
185toolkit, materials and material-volume assignments are specified in
186geometry input classes, in the detector constructor file. When FLUGG
187initializes the geometry, material information is read from
188GEANT4 detector description, and translated into FLUKA-formatted
189input cards.
190So a first dummy run must be executed; the newly created file containing
191GEANT4 material specifications and volume-material assignments
192(flukaMat.inp) must be included into the FLUKA input file where
193additional properties can still be defined. Other useful information,
194like FLUGG geometry volume names and indexes (together with repetition
195numbers for replicated or parameterized volumes!) are dump in
196Volumes_index.inp.
197
198Now you are ready to run mainFLUGG (see rfluka script in /flugg/
199examples/fluka).
200
201
2022.2 Examples module
203--------------------------------------------------------------------
204This module collects a set of user examples aimed to demonstrate to
205a user how to make correct use of the FLUGG toolkit by implementing
206those user-classes which a Geant4 user is supposed to customize
207in order to define his/her own detector geometry setup.
208This set of examples covers some possible general use-cases
209for actual detector simulation for HEP.
210
211 AlAuAl
212 - series of slab of different elements (Al, Au, Al), which total
213 thickness is of the order of the electron range;
214 - multiple scattering at boundaries (handle delicate situations such
215 as grazing angles, backscattering, deflections at boundaries);
216 Fluka input files: alaual.inp, wa_50m.pemf
217
218 BiasEx
219 - 500 MeV protons on a thick Cu target: the generated neutrons
220 propagate in a concrete shield;
221 - fluka biasing techniques are applied to achieve variance
222 reduction;
223 Fluka input files: Bias.inp, wa_50m.pemf
224
225 MagSphereNotRep
226 - test-geometry with spheres and tubs;
227 - tracking in magnetic field;
228 Fluka input files: MagSphereNotRep.inp, t36.pemf
229
230 T36flugg
231 - Test-36 em-hadronic calorimeter;
232 - Full "ordinary" processes;
233 - no magnetic field;
234 Fluka input files: T36.inp, t36.pemf
235
236
237
238Appendix A. FLUKA input --> FLUGG input
239********************************************************
240When transposing a fluka input in a flugg input you need
241to:
242
243a) Update the following fluka cards substituting fluka
244region indexes with G4 geometry volume indexes: (in
245parenthesis the WHAT() with region numbers):
246
247ASSIGNMAT (2,3,4)
248BEAMPOS (6)
249BIASING (4,5,6)
250DETECT (6; contin.card:2-6)
251EMF-BIAS (4,5,6)
252EMFCUT (4,5,6)
253EMFRAY (2,3,4)
254EXPTRANS (3,4,5)
255GEOBEGIN/END no WHAT exept COMBINAT; throw
256 away everything between GEOBEGIN/END
257GLOBAL (1)
258LOW-BIAS (4,5,6)
259LOW-DOWN (4,5,6)
260RESNUCLEI (5,6)
261STEPSIZE (3,4,5)
262TIMECUT (5,6)
263USRBDX (4,5)
264USRBIN (4,5,6; contin.card:1,2,3,4,5,6)
265USRCOLL (4)
266USRTRACK (4)
267USRYIELD (4,5)
268WW-FACTO (4,5,6)
269
270b)integrate the following material cards with information:
271DELTARAY, EMF-BIAS, EMF-CUT, EMF-FIX, EMF-FLUO, EVXTEST,
272FLUKAFIX, LAM-BIAS, LANDAU, LOW-MAT, MAT-PROP, MULSOPT,
273OPT-PROP, PAIRBREM, PHOTONUC; and in MAPA and PEMF file,
274which contain detailed information about materials.
275
276When comparing fluka and FLUGG runs, REMEMBER to:
2771) check that coordinate system is the same in fluka geometry
278and in GEANT4 geometry; if it is not, update position and beam
279direction.
2802) check how events are the scored!
281
282
283Appendix B. GEANT4 example --> FLUGG example:
284****************************************************************
2850) Copy /src and /include geant4 examples directories in emptyEx/
2861) Delete all classes exept:
287 - Detector Construction;
288 - Detector Parameterization;
289 - Magnetic Field Construction;
2902) Delete corresponding "#include ..." lines in Detector
291Construction source file and variables definitions in the constructor,
292and corresponding class declarations and variable declaration
293in Detector Construction include file.
2942b) Delete #include "G4RunManager.hh" and lines where RunManager is
295invoked.
2963) Delete Detector messenger, initialization and destruction, delete
297code lines where Sensitive Detector is set (be aware of memory leaks!).
2984) Delete code lines where parameterization of processes for fast
299simulation is set (and visualization of ghost volumes).
300Delete commands for interactive definition of the calorimeter
301
302
303
304Appendix C. How to update FLUGG with new Geant4 releases
305****************************************************************
306For updating FLUGG with new Geant4 releases the following
307operations are required:
308
3091) from flugg/source: gmake clean_all to remove the previous
310installation;
311
3122) unzip and untar Geant4 release;
313
3143) set environment variable for paths to Geant4 (G4INSTALL)
315 and Flugg (FLUGGINSTALL)
316
3174) run update_source.sh script
318
319This will replace files placed in include and src sub-directories
320of the following directories:
321geant4/source/geometry ---> flugg/source/geometry
322geant4/source/graphics_reps ---> flugg/source/graphics_reps
323geant4/source/material ---> flugg/source/material
324geant4/source/global ---> flugg/source/global
325geant4/source/intercoms ---> flugg/source/intercoms
326The Geant4 makefiles are modified for Flugg; old Flugg
327makefiles are kept and renamed to GNUmakefile.flugg and kept.
328
3295) now you must add "UpdateNavigatorHistory" member function to
330G4Navigator class; insert the following declaration in
331"flugg/source/geometry/volumes/include/G4Navigator.hh" file:
332
333// flugg member function: reinitialization of navigator history with
334// secondary particle history banked on fluka side
335 void UpdateNavigatorHistory(const G4NavigationHistory* newNavHistory);
336
3376) And append the following definition to
338"flugg/source/geometry/volumes/src/G4Navigator.cc" file:
339
340void G4Navigator::UpdateNavigatorHistory(const G4NavigationHistory* newNavHistory)
341{
342 ResetStackAndState();
343 fHistory = *newNavHistory;
344 SetupHierarchy();
345}
346
3477) run update_config.sh
348
349This will replace makefiles placed in config directory
350with new ones from Geant4 modified for Flugg;
351old makefiles are kept and renamed (by adding .flugg extension).
352!!! binmake.gmk has to be updated by hands.
353In case no major modifications were done in config
354in new Geant4 release the old binmake.gmk may be used without
355modofications.
356