# $Id: README,v 1.21 2005/03/17 19:48:27 daquinog Exp $ # ------------------------------------------------------------------- # GEANT4 tag $Name: $ # ------------------------------------------------------------------- Simulation of the TIARA experiment using importance sampling ============================================================ This example is a simulation of the neutron shielding experiment TIARA see http://idsun1.kek.jp/nakao/research/tiara/tiara.htm. The example is meant to provide a realistic example for applying geometrical importance sampling (geometrical splitting and Russian roulette). In the TIARA experiment neutrons of two different energy distributions created by 43 MeV and 68 MeV protons bombarding a 7Li target are measured behind several shields. The simulation starts from the neutron spectra. In this example the interactions of the neutrons with the (concrete) shields are simulated and energy dependent neutron fluxes are measured behind the shields. Users may choose to run the simulation for different shielding configuration with or without importance sampling. The simulated neutron fluxes are compared to the published experimental data. The efficiency of applying importance sampling depends strongly on the shield thickness and importance configuration. The efficiency of the simulations may be obtained as FOM values. See also "Geant4 User's Guide For Application Developers", Chapter "Toolkit Fundamentals" Section "Event Biasing Techniques" and references there. The example has been tested on CERN RH 7.3 with the gcc-3.2.3 and gcc-2.95.2 compilers. Note for system testing without analysis: see points 1.1, 1.3 and 3.2. 1) Setting the environment ========================== You must compile Geant4 with: "G4LIB_BUILD_SHARED" set to 1. You need to set: "NeutronHPCrossSections" (e.g. pointing to a directory containing G4NDL3.7) Three examples are given of how to set environment variables in the three cases: 1.1) PI via AFS (most simple): -------------------- You have access to afs and you want to use PI for the analysis: Set the following environment variables: "G4ANALYSIS_USE" "PI_BASE_DIR" (where PI has been installed) "SWIG_BASE_DIR" (where SWIG has been installed) Finally source the script envCommon.csh from the directory where you have Tiara installed, e.g. ${G4INSTALL}/examples/advanced/Tiara 1.2) No afs but a local PI and SWIG installation: ----------------------------------------------------- You don't use afs but you have a local installation of SWIG and PI Set the following environment variables: "G4ANALYSIS_USE" "PI_BASE_DIR" "SWIG_BASE_DIR" Finally source the script envCommon.csh from the directory where you have Tiara installed, e.g. ${G4INSTALL}/examples/advanced/Tiara 1.3) No afs, no PI and no SWIG (e.g. for system testing): ------------------------------------------------------------- You don't want to use PI and SWIG and you don't have afs access. Make sure "G4ANALYSIS_USE" is unset (e.g. unsetenv G4ANALYSIS_USE or setenv G4ANALYSIS_USE 0) Note 1: python must be built against a "libc". You may do this by creating a shared library by a command similar to this "ld -shared -o libpython2.3.so --whole-archive libpython2.3.a /usr/lib/libc.so" Set the following environment variables: "PYTHONVERSION" (2.3 or higher) "PYTHON_BASE_DIR" (e.g. to /usr) "SWIG_VERSION" (e.g. 1.3 or higher) "SWIG_BASE_DIR" (e.g. /usr) "CLHEP_BASE_DIR" (e.g. to /opt/local) Finally source the script envCommon.csh from the directory where you have Tiara installed, e.g. ${G4INSTALL}/examples/advanced/Tiara NOTE 2: Passing from a simulation WITH to another WITHOUT analysis implies that the G4ANALYSIS_use should be unset and that the SWIG-wrapper scripts in the directory TiaraWrapper should be deleted. Normally, the whole code should be compiled again using gmake clean_all and, afterwards, gmake. The same procedure should be followed also passing from a simulation WITHOUT to another WITH analysis. 2) Building the example ======================= Geant4 has to be compiled using G4LIB_BUILD_SHARED 1 and the one of the above environment settings have to be set. Type "gmake". 2.1) In more detail ------------------- Geant4 must be compiled into granular shared libraries. Therefore before compiling Geant4 set "G4LIB_BUILD_SHARED" to "1". External packages used in this example are PI, SWIG and Python. 2.2) Cleaning up ---------------- To remove the files created by swig ( *_wrap.cc, the corresponding .py files) use "gmake swigClean". To remove the directories of compiled code related to this example under $G4WORKDIR/tmp/$G4SYSTEM/ use "gmake tiaraClean". To remove all the files created during the previous compilation, use "gmake clean_all". 3) Running the example: ======================= 3.1) Using PI ----------------- Change to the sub directory "run" and execute "runSim.py". "runSim.py" runs an example configuration which may be changed by the user. The results of the simulation are stored in the directory "simData". The script "runSim.py" periodically prints scoring information to the screen. It also prints out the relative path of a ".shelve" file. This file can be used to access results of the simulation. In case the example was build using analysis results may be viewed e.g. using python or ROOT: 1) Start python 2) type: import dataAcess 3) type: p = dataAcess.ExpMcPlot (shelveFileName,detectorposition) where "shelveFileName" is the name (enclosed in quotes) of the shelve file created during the execution of runSim.py. The name is printed on the screen during execution of runSim.py. "detectorposition" may be "00, "20" or "40" and stand for the detectors 00, 20, 40 cm off beam axis respectively. 4) type: p.display () 5) type: import extractShelve 6) type: extractShelve.getFluxes (p.she) p.she is the shelve object containing simulation results. This prints the FOM values for the used detectors for two energy regions below and in the peak region. The FOM should be compared to unbiased simulations. To run an unbiased simulation set the importance values to one (see runSim.py) Note: the output files written after every run are incremental! Meaning the file with the highest run number contains the data from all the runs! The modules (dataAcess, extractShelve) imported in the above steps are placed in source/py_modules in files named after the module ending with ".py". Since the simulation time used by "runSim.py" is only 5 minutes the calculated results have large errors. If you want to see a better result do the following changes in "runSim.py". Extend the total run time to e,g, 2 hours by setting: "totalTime = 2 * myUtils.hour", set the print out period to 30 minutes by setting: "timeForOneRun = 30 * myUtils.min". 3.2) Not using PI (mainly for system testing) ------------------------------------------------- Change to the sub directory "run" and execute runSimNoAnalysis.py. 4) Content of the directory: ============================ envCommon.csh - a script to setup environment variables in case the above one of the above environment settings have been done beforehand. GNUmakefile - for building the example data / - directory containing experimental data expDataOrig - experimental data taken from http://idsun1.kek.jp/nakao/research/tiara/tiara.htm expDataConverted - some of the experimental data and the source spectra converted into Anaphes DataPointSet and stored in Anaphes xml format source / - directory containing the source code tiara - C++ source code CLHEPWrapper - wrapper classes for usage in python \include\CLHEP.i - specification file for swig \src\CLHEP_wrap.cc - wrapper created with swig G4KernelWrapper - wrapper classes for usage in python TiaraWrapper - wrapper classes for usage in python py_modules - python modules for running and analysing swig.gmk - makefile rules for using swig run / - directory for running the example runSim.py - executable example script runSimNoAnalysis.py - executable script for running without analysis 5) Technicalities about this example =================================== This example is composed out of a layer of classes written in C++ (source/tiara/include, source/tiara/src), a layer of python shadow classes created by swig (source/CLHEPWrapper, source/G4KernelWrapper, source/TiaraWrapper) and a layer of python modules (source/py_modules). The C++ layer under source/tiara provides lower level classes closely related to the Geant4 kernel. The shadow classes in the source/*Wrapper directories provide classes that may be instantiated in a python script or session. This way the lower level C++ code can be used directly for scripting in python. The shadow classes are declared in the files with extensions ".i" in the source/*Wrapper/include directories. Swig is used to create C++ code for a library that can be loaded into python and python modules (files with extensions .py in the source/*Wrapper directories). When the python modules created by swig are imported into python (in a session or a script) the corresponding C++ library is automatically loaded as well. The python modules in source/py_modules provide classes and functions that may be changed or customized more frequently than the C++ classes in source/tiara. These classes complete the construction of geometries, take care of the procedure of setting up the simulation, the run sequence and the analysis after the simulation has been ran. The script runSim.py is an commented example of using the python modules to run a simulation. 6) Note about how to call the hadronic physics lists in runSim.py and runSimNoAnalysis.py ========================================================================================= It is only necessary to change the physList value in runSim.py or runSimNoAnalysis.py. In the example, there are 4 available physics lists, but of course the user can use whatever physics lists he/she likes and present in the Geant4-7.0 repository. In such a case, the user should also modify the /source/TiaraWrapper/include/Tiara.i file in order to create an instantiation of the physics list class. In particular, just follow the same lines already used for the six available physics lists.