Reconstruction of RAW data. Introduction of cluster finder (A. de Caro)

[u/mrichter/AliRoot.git] / Flugg / documents / README-FLUGG

# $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.