ProcessLevel/FinalState/README.md

0001 # Description
0002
0003 This example allows the simulation of hadron-nucleus inelastic nuclear interactions,
0004 and the study of the resulting final states.
0005
0006 It is an adaptation of `Hadr09` example.
0007 It offers all `Hadr09` features, and adds the possibility
0008 of accessing hadron-nucleus inelastic nuclear interaction final states FROM `FLUKA`.
0009
0010 With respect to the `Hadr09` example, the program also adds
0011 the possibility of PLOTTING the final state:
0012 secondaries energy spectra, and residual nuclei distributions.
0013 All plots (created via the G4 analysis manager) can be dumped
0014 to any of the usually supported formats (e.g. ROOT format),
0015 as well as in a Flair-compatible format.
0016 Regarding the extension of `G4H1` to insure `Flair` compatibility,
0017 see `geant4/examples/extended/hadronic/FlukaCern/utils`.
0018
0019 The class `HadronicGenerator` is the "generator".
0020 The main hadronic models (`CernFLUKAHadronInelastic`, `FTFP`, `QGSP`, `BERT`, `BIC`, `IonBIC`, `INCL`) are available.
0021 See `include/HadronicGenerator.hh` for more detailed information.
0022 In the `HadronicGenerator`, one can activate/desactivate coalescence and heavy fragments evaporation for `CernFLUKAHadronInelastic`.
0023
0024 The main, `HadNucIneEvents.cc`, shows an example of how to use the event generator.
0025 In `HadNucIneEvents.cc`, one can select the physics models,
0026 as well as the projectile hadron, its energy, its direction, the target material, and the number of collisions.
0027
0028 Note that the Geant4 run manager is not used.
0029
0030 Before you can access the `FLUKA` hadron-nucleus inelastic models in this example,
0031 you will need to install and setup `FLUKA` and its interface.
0032 See the compulsory "Dependencies" paragraph below.
0033
0034 A version of the interface to `FLUKA` is directly located at `geant4/examples/extended/hadronic/FlukaCern/FlukaInterface`.
0035 Note that for consistency, all calls to the random engine rely on the G4 random engine (including the calls from within the downloaded `FLUKA` release; see the `FlukaInterface` `GNUmakefile` to see how this is handled).
0036
0037
0038 # FLUKA inelastic hadron-nucleus interactions
0039
0040 Hadron-NUCLEON interaction models are based on resonance production and decay below a few GeV,
0041 and on the Dual Parton model above.
0042 Hadron-NUCLEUS interactions: the PEANUT package includes
0043 a detailed Generalised Intra-Nuclear Cascade (GINC) and a preequilibrium stage,
0044 followed by equilibrium processes: evaporation, fission, Fermi break-up, gamma deexcitation.
0045 ```
0046 A. Ferrari and P. Sala, “The Physics of High Energy Reactions,” in Proc. Workshop on Nuclear Reaction Data and Nuclear Reactors Physics, Design and Safety, p. 424, World Scientiﬁc, 1998.
0047 A. Ferrari and P. Sala, “Nuclear reactions in Monte Carlo codes,” Radiat. Prot. Dosimetry, vol. 99, no. 1-4, pp. 29–38, 2002.
0048 ```
0049
0050
0051 # Dependencies
0052
0053 ### Environment
0054 - **gcc** >= 7 (Linux) and **gcc** >= 9 (MacOS)
0055 In practice, a recent version is recommended, at least `gcc >=10`.
0056 ```
0057 gcc --version
0058 ```
0059
0060 - **CMake** >= 3.16...3.21
0061 ```
0062 cmake3 --version
0063 ```
0064
0065 - **G4** >= 11.0.3 (Not tested on older G4 releases: might still work, but with no guarantee).
0066 IMPORTANT: YOU NEED TO SOURCE YOUR G4 ENVIRONMENT.
0067 It needs to be sourced in whichever terminal you want to build / run a G4 application with the `FLUKA` interface.
0068 ```
0069 source path_to_geant4/install/bin/geant4.sh
0070 which geant4-config   # NB: Your geant4-config should support the modern CMake way of building G4.
0071 ```
0072
0073 - **Easy setup on lxplus** (lxplus7):
0074 All you need to do on lxplus, to setup an environment satisfying all the conditions above, is, for example:
0075 ```
0076 source /cvmfs/sft.cern.ch/lcg/releases/gcc/10.1.0/x86_64-centos7/setup.sh
0077 source /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/CMake-setup.sh
0078 # NB: Your geant4.sh is at: /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/bin/geant4.sh
0079 ```
0080
0081 ### `FLUKA4`
0082 Release: >= **4-3.2**
0083
0084 Please install the latest `FLUKA` release.
0085 (1) You first need to register (and accept the licence when relevant): https://fluka.cern/download/registration
0086 (2) You can then download the `binary libraries` (or potentially the `source code` package, depending on your case):
0087 https://fluka.cern/download/latest-fluka-release.
0088 (3) Follow the `FLUKA` installation instructions: https://fluka.cern/documentation/installation
0089 In particular, for a Linux/MacOS install: https://fluka.cern/documentation/installation/fluka-linux-macos
0090 They will show you how to setup `FLUKA`.
0091 If (and only if) you went for the source code package option, you will need to build `fluka`, and, in addition, to do `make cpp_headers` at `path_to_fluka/src`.
0092 (4) Eventually, all you need are the headers `fluka_repo/include`, libraries `fluka_repo/lib`, and data `fluka_repo/data`. Check that they are not empty.
0093 Do not forget to add `/path_to_fluka/bin` to your `PATH`. Check with `which fluka`.
0094
0095 ### `FlukaInterface`
0096 A version of the G4-FLUKA interface (`FLUKA` hadron-nucleus inelastic physics)
0097 is located at `geant4/examples/extended/hadronic/FlukaCern/FlukaInterface`.
0098 You will first need to build the interface to `FLUKA`, and create the environment scripts.
0099 ```bash
0100 $ cd geant4/examples/extended/hadronic/FlukaCern/FlukaInterface/
0101 # Check with `which fluka` that fluka executable is added to your `PATH`.
0102 $ source path_to_geant4/install/bin/geant4.sh
0103 $ make interface
0104 $ make env       # Creates `env_FLUKA.sh` and `env_FLUKA_G4_interface.sh`
0105 ```
0106 IMPORTANT: `env_FLUKA_G4_interface.sh` needs to be sourced in whichever terminal
0107 you want to build / run a G4 application with the `FLUKA` interface.
0108
0109
0110 # Build this example
0111 ```bash
0112 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/FinalState/
0113 # Check with `which fluka` that fluka executable is added to your `PATH`.
0114 $ source path_to_geant4/install/bin/geant4.sh
0115 $ source ../../FlukaInterface/env_FLUKA_G4_interface.sh
0116 $ mkdir build
0117 $ cd build
0118 $ cmake3 -DG4_USE_FLUKA=1 ..
0119 $ make -j8
0120 ```
0121
0122
0123 # Run this example
0124 ```bash
0125 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/FinalState/
0126 # Check with `which fluka` that fluka executable is added to your `PATH`.
0127 $ source path_to_geant4/install/bin/geant4.sh
0128 $ source ../../FlukaInterface/env_FLUKA_G4_interface.sh
0129 $ ./build/HadNucIneEvents
0130 ```
0131
0132
0133 # Study the final states
0134 All plots are dumped at the end of the run in `all_secondaries.ext`.
0135 2 formats are supported: `ROOT` and `Flair`.
0136
0137
0138 - You can use `ROOT`:
0139 ```bash
0140 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/FinalState/
0141 $ root all_secondaries.root
0142 ```
0143
0144 - Alternatively, the use of `Flair` is also supported.
0145 Please see http://flair.web.cern.ch/flair/download.html for `Flair` download.
0146 `Flair` tutorials are also available from that website.
0147 You can download the package corresponding to your distribution at the top of the page
0148 (no need for `geoviewer`, which is for geometry display). Then look at the requirements & installation instructions at the bottom of the page.
0149 If you face issues installing `Flair`, you can get support at: https://fluka-forum.web.cern.ch/c/installation/
0150
0151 An example file, showing how to directly visualize the final states with Flair, is provided in this G4 example.
0152 By default, it directly provides comparison plots:
0153 `FTFP_BERT` versus `QGSP_BERT` versus `CernFLUKAHadronInelastic`, 7TeV proton on C.
0154 You can very easily adapt it to any study of interest (choice of physics models, choice of secondaries, etc).
0155 ```bash
0156 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/FinalState/
0157 $ mkdir -p results/FLUKAHadronInelastic results/FTFP_BERT results/QGSP_BERT
0158 $
0159 $ # Choose physics case (modify HadNucIneEvents.cc), compile the G4 example, then run physics case:
0160 $ cd results/FLUKAHadronInelastic
0161 $ ../../build/HadNucIneEvents
0162 $ # Etc for EACH physics case: FLUKAHadronInelastic, FTFP_BERT, QGSP_BERT.
0163 $
0164 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/FinalState/
0165 $ ./update_final_state_flair_file.sh # Update `Det` indices in Flair file, to the ones observed in your simulation.
0166 $ flair study_final_state.flair &
0167 ```
0168 In the `Plot` tab, you can select the plot of interest in the left column,
0169 and then click `Plot` (top banner, yellow button).
0170 You can select a physics case by clicking on its name in the `Detectors` box (center). You can then decide to change its color, line width (`Options` box). You can decide to plot it or not, by selecting / unselecting `graph` in the `Show` box (in the center).
0171 IMPORTANT: You can select any secondary data (or residual nuclei data) which was created,
0172 by chosing in the `Det` selection (button on the right).
0173 IMPORTANT: If a secondary does not appear in the `Det` drop-down menu, it means it is not part of the final state. In that case, you will want to unselect `graph`, so that no other secondary (see `Det`) is plotted.
0174 You can change the path of the data file by clicking on the folder button (button on the right).
0175 You can set the plots extrema, as well as select or unselect the log format, in the top right corner.
0176
0177
0178
0179
0180
0181