-------------------------------------------------------
----------------- Installing Geant4 -------------------
-------------------------------------------------------
The recommended way to install Geant4 is to compile it from source, which can be
downloaded from:
  https://geant4.web.cern.ch/geant4/support/download.shtml
  
Installation instructions are given here for Linux, OSX and Windows, as well as
information how to build an application:
  http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/InstallationGuide/html/
  
For all architectures cmake is required to build Geant4 libraries and applications
(https://cmake.org/download/ if not installed already).
  
During the build process, for visualization of events, include the following option:
-DGEANT4_USE_OPENGL_X11=ON (linux, OSX)
-GEANT4_USE_OPENGL_WIN32=ON (Windows)
For details see:
http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/InstallationGuide/html/ch02s03.html

The option -DGEANT4_INSTALL_DATA=ON can also be used to install all process data instead
of specific sets later on.

-------------------------------------------------------
------- Using Geant4 on login.uni-freiburg.de ---------
-------------------------------------------------------
As installing Geant4 in e.g. the home folder of an RZ account can take too much space (and
CIP pool machines lack several common libraries complicating the build process)
I installed Geant4 on the scratch disk of login.uni-freiburg.de, which is reachable
by ssh using an RZ account. cmake is still required to build and compile the actual main
program, which is not available by default on that node. Please e.g. do:

wget http://www.cmake.org/files/v3.4/cmake-3.4.0.tar.gz
tar xvzf cmake-3.4.0.tar.gz 
cd cmake-3.4.0/
./configure --prefix=$HOME/cmake
make
make install
PATH=$PATH:$HOME/cmake/bin

The last command has to be done after every login. In addition source the geant4
installation (also at every login):
cd /scratch/u/fr1016/geant4.10.02-install/bin/
source geant4.sh
cd -

-------------------------------------------------------
------ Building the executable for the exercise -------
-------------------------------------------------------
The folder containing the code for the exercise and this README is the source
folder, and with cmake the application is typically installed into a different
directory. The main program can be compiled and built using e.g. (when in the
source folder).  The uni-freiburg.de server insists on the "User-Agent:" header
to be present, but its value is arbitrary.

wget --header "User-Agent:Netscape1.0" http://portal.uni-freiburg.de/jakobs/dateien/vorlesungsdateien/particledetectors/exercise.zip
unzip exercise.zip
cp -R exercise_clean exercise
mkdir run_exercise
cd run_exercise
cmake -DGeant4_DIR=/scratch/u/fr1016/geant4.10.02-install/lib/Geant4-10.2.0/ -DWITH_GEANT4_VIS=ON ../exercise/
make

In some setups, it is necessary to remove the keyword "G4ThreadLocal" from the
file src/DetectorConstruction.cc (line 25) for the compilation to succeed.

The program is then started in interactive mode by ./exercise, see more info below.

-------------------------------------------------------
---------------- Structure of code --------------------
-------------------------------------------------------
The application used for the exercise has a main program exercise.cc, a few macro files
(.mac) and several classes that are defined and implemented in the include and src
directories. The important ones are:
- PrimaryGeneratorAction
Initialized the source of incident particles, in this case a "particle gun"
- DetectorConstruction
Where the design of the detector is defined.
- RunAction
Things that are done once per run, e.g. defining histograms and root file outputs and
writing results out.
- EventAction
All things that need to be done once per "event" (one event being the impact of one
incident particle), e.g. filling deposited energy into a histogram.
- SteppingAction
The simulaton is using a stepping algorithm, here there all things that have to be done
once per step, e.g. adding the energy deposited in this step to a counter in the
EventAction class.

For the problem set, the following classes will have to be modified (while e.g.
exercise.cc and others don't need to be touched):
- DetectorConstruction
- RunAction
- EventAction
- SteppingAction

To do large statistics runs in batch mode (no visualization or interaction), a macro can
be used and modified:
- run.mac

-------------------------------------------------------
---------------- Running the code ---------------------
-------------------------------------------------------
The program can be run in interactive and in batch mode. For interactive mode this is done
simply by:
./exercise
The geometry, particle gun, ... are then initialized and tested, ending with a command
prompt.
To run one event in the prompt:
/run/beamOn 1
The energy of the particle gun can be changed by:
/gun/energy 1 GeV
and the particle type by:
/gun/particle mu+
or similar.
Several events can be simulated and written out as one run by e.g.:
/run/beamOn 10
for 10 events. The program can be closed using 'exit'.

For larger event numbers it is typically best to run in batch mode, e.g. started by:
./exercise -m run.mac
An unmodified run.mac will generate 1000 events, printing the progress every 100 events.
Be advised that this can take some time.

-------------------------------------------------------
------ Modifying the detector and readout -------------
-------------------------------------------------------
- DetectorConstruction.cc already includes the option of having lead absorber layers, the
only thing that needs to be done is changing the variable absThickness.

- RunAction.cc can be modified to add histograms, define additional information to be
written out to the root file, simple text output and similar. Examples for all these are
included and can be copied and modified.

- EventAction.cc has to be modified to fill any new ntuple columns or histograms, 
following the examples, as well as reset all variables keeping track of the event at the 
start of each event. If new variables are needed:

- EventAction.hh defines the event level variables and simple functions to increment them.
For total energy and track length and per layer energy everything is in place already, so
using these examples e.g. per layer track length counters can be added.

- SteppingAction.cc increments the counters of EventAction per simulation step, here some
calls have to be added for per layer readout. At the appropriate place a useful command to 
identify the layer, to then call EventAction::AddLayer(G4int lay, G4double de), is 
provided as a comment.

These are the only files where changes are strictly necessary to solve the problem set, 
but if feeling confident the program can be adapted to ones needs as seen fit of course.

-------------------------------------------------------
------ Analysis of the output of the program -----------
-------------------------------------------------------
There are three levels of output provided by the program, in addition to a visualization:
- simple text output allowing a quick look at what is happening and the detector response
and performance
- complete histograms are saved in output.root. These can be accessed by opening ROOT and
then e.g. starting a browser by "new TBrowser"
- output is saved event by event into a ROOT tree, which can also be accessed using a ROOT
TBrowser, or e.g. TTree->Draw() commands (see ROOT documumentation). Another slightly more
involved option is to use TTree->MakeClass("someName"), which creates a .h and .C script
which can be started with ROOT someName.c, or inside root ".x someName.c". The code
generated by ROOT contains some pointers how to create a more powerful, compared to
TTree->Draw(), analysis.
Technically the problem set could be solved using only text output and some other plotting
program, but some interaction with root is recommended (even if only using the TBrowser).

In case there are technical issues or questions that remain unsolved after spending some 
time and google searches on, don't hesitate to write an email to:
frederik.ruehr@cern.ch



