ProcessLevel/CrossSection/README.md

0001 \page ExampleCrossSection Example CrossSection
0002
0003 # Description
0004
0005 This FlukaCern example allows the study of G4 cross-sections,
0006 and in addition, of the `FLUKA` hadron-nucleus reaction cross sections.
0007
0008 The user can printout any particle-material XS.
0009 The XS are exactly the ones defined in any G4 physicsList chosen by the user,
0010 or from `FLUKA` (hadron-nucleus inelastic case).
0011
0012 In the input file, the user can set:
0013 - projectile.
0014 - target material (element, compound or even mixture).
0015 - plotting options.
0016
0017 All plots (created via the G4 analysis manager) can be dumped
0018 to any of the usually supported formats (e.g. `ROOT` format),
0019 but also in a Flair-compatible format.
0020 Regarding the extension of `G4H1` to insure `Flair` compatibility,
0021 see `geant4/examples/extended/hadronic/FlukaCern/utils`.
0022
0023 Note that the Geant4 run SERIAL manager is used, since `FLUKA` is single-threaded
0024 (in actual `FLUKA` runs, parallelism is achieved via a multi-processing approach).
0025
0026 Before you can access the `FLUKA` hadron-nucleus inelastic model in this example,
0027 you will need to install and setup `FLUKA` and its interface.
0028 See "Dependencies" paragraph below.
0029
0030 A version of the interface to `FLUKA` is directly located at `geant4/examples/extended/hadronic/FlukaCern/FlukaInterface`.
0031
0032
0033 # Dependencies
0034
0035 ### Environment
0036 - **gcc** >= 7 (Linux) and **gcc** >= 9 (MacOS)
0037 In practice, a recent version is recommended, at least `gcc >=10`.
0038 ```
0039 gcc --version
0040 ```
0041
0042 - **CMake** >= 3.16...3.21
0043 ```
0044 cmake3 --version
0045 ```
0046
0047 - **G4** >= 11.0.3 (Not tested on older G4 releases: might still work, but with no guarantee).
0048 IMPORTANT: YOU NEED TO SOURCE YOUR G4 ENVIRONMENT.
0049 It needs to be sourced in whichever terminal you want to build / run a G4 application with the `FLUKA` interface.
0050 ```
0051 source path_to_geant4/install/bin/geant4.sh
0052 which geant4-config   # NB: Your geant4-config should support the modern CMake way of building G4.
0053 ```
0054
0055 - **Easy setup on lxplus** (lxplus7):
0056 All you need to do on lxplus, to setup an environment satisfying all the conditions above, is, for example:
0057 ```
0058 source /cvmfs/sft.cern.ch/lcg/releases/gcc/10.1.0/x86_64-centos7/setup.sh
0059 source /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/CMake-setup.sh
0060 # NB: Your geant4.sh is at: /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/bin/geant4.sh
0061 ```
0062
0063 ### `FLUKA4`
0064 Release: >= **4-3.2**
0065
0066 Please install the latest `FLUKA` release.
0067 (1) You first need to register (and accept the licence when relevant): https://fluka.cern/download/registration
0068 (2) You can then download the `binary libraries` (or potentially the `source code` package, depending on your case):
0069 https://fluka.cern/download/latest-fluka-release.
0070 (3) Follow the `FLUKA` installation instructions: https://fluka.cern/documentation/installation
0071 In particular, for a Linux/MacOS install: https://fluka.cern/documentation/installation/fluka-linux-macos
0072 They will show you how to setup `FLUKA`.
0073 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`.
0074 (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.
0075 Do not forget to add `/path_to_fluka/bin` to your `PATH`. Check with `which fluka`.
0076
0077 ### `FlukaInterface`
0078 A version of the G4-FLUKA interface (`FLUKA` hadron-nucleus inelastic physics)
0079 is located at `geant4/examples/extended/hadronic/FlukaCern/FlukaInterface`.
0080 You will first need to build the interface to `FLUKA`, and create the environment scripts.
0081 ```bash
0082 $ cd geant4/examples/extended/hadronic/FlukaCern/FlukaInterface/
0083 # Check with `which fluka` that fluka executable is added to your `PATH`.
0084 $ source path_to_geant4/install/bin/geant4.sh
0085 $ make interface
0086 $ make env       # Creates `env_FLUKA.sh` and `env_FLUKA_G4_interface.sh`
0087 ```
0088 IMPORTANT: `env_FLUKA_G4_interface.sh` needs to be sourced in whichever terminal
0089 you want to build / run a G4 application with the `FLUKA` interface.
0090
0091
0092 # Build this example
0093 ```bash
0094 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/CrossSection/
0095 # Check with `which fluka` that fluka executable is added to your `PATH`.
0096 $ source path_to_geant4/install/bin/geant4.sh
0097 $ source ../../FlukaInterface/env_FLUKA_G4_interface.sh
0098 $ mkdir build
0099 $ cd build
0100 $ cmake3 -DG4_USE_FLUKA=1 ..
0101 $ make -j8
0102 ```
0103
0104
0105 # Run this example
0106 ```bash
0107 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/CrossSection/
0108 # Check with `which fluka` that fluka executable is added to your `PATH`.
0109 $ source path_to_geant4/install/bin/geant4.sh
0110 $ source ../../FlukaInterface/env_FLUKA_G4_interface.sh
0111 # Edit all_XS.in (choice of particle, material, energy range...)
0112 # XS used by FTFP_BERT_HP physics list:
0113 $ ./build/HadronNucleusXS all_XS.in FTFP_BERT_HP
0114 # XS used by G4_HP_CernFLUKAHadronInelastic_PhysicsList physics list:
0115 $ ./build/HadronNucleusXS all_XS.in G4_HP_CFLUKAHI
0116 ```
0117
0118
0119 # Study the cross-sections
0120 All plots are dumped at the end of the run in `all_XS.ext`.
0121 2 formats are supported: `ROOT` and `Flair`.
0122
0123
0124 - You can use `ROOT`:
0125 ```bash
0126 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/CrossSection/
0127 $ root all_XS.root
0128 ```
0129
0130 - Alternatively, the use of `Flair` is also supported.
0131 Please see http://flair.web.cern.ch/flair/download.html for `Flair` download.
0132 `Flair` tutorials are also available from that website.
0133 You can download the package corresponding to your distribution at the top of the page
0134 (no need for `geoviewer`, which is for geometry display). Then look at the requirements & installation instructions at the bottom of the page.
0135 If you face issues installing `Flair`, you can get support at: https://fluka-forum.web.cern.ch/c/installation/
0136
0137 An example file, showing how to directly visualize all XS with `Flair`,
0138 is provided in this G4 example.
0139 By default, it directly provides comparison plots:
0140 `FTFP_BERT_HP` versus `G4_HP_CernFLUKAHadronInelastic`.
0141 One can very easily adapt it (directly from `Flair` GUI) to any study of interest.
0142 ```bash
0143 $ cd geant4/examples/extended/hadronic/FlukaCern/ProcessLevel/CrossSection/
0144 $ mkdir -p results/FTFP_BERT_HP results/G4_HP_CernFLUKAHadronInelastic
0145 $ # First run the example for FTFP_BERT, G4_HP_CernFLUKAHadronInelastic, and move the results!
0146 $ ./build/HadronNucleusXS all_XS.in FTFP_BERT_HP
0147 $ mv all_XS.hist results/FTFP_BERT_HP
0148 $ ./build/HadronNucleusXS all_XS.in G4_HP_CFLUKAHI
0149 $ mv all_XS.hist results/G4_HP_CernFLUKAHadronInelastic
0150 $
0151 $ flair study_all_XS.flair &
0152 ```
0153 In the `Plot` tab, you can select the plot of interest in the left column,
0154 and then click `Plot` (top banner, yellow button).
0155 You can select a physics list 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).
0156 You can change the path of the data file by clicking on the folder button (button on the right).
0157 You can set the plots extrema, as well as select or unselect the log format, in the top right corner.
0158
0159
0160