FlukaCern/FlukaInterface/README.md

0001 # Interface to `FLUKA` physics models
0002
0003 This is an interface to the `FLUKA` CERN hadron inelastic physics.
0004 It can be used by ANY G4 application (including the experimental frameworks, provided they are relying on G4 physics lists already).
0005
0006 Note that this is a generic guide to be able to use the `FLUKA` interface from *any* G4 application.
0007 If you are trying to build / run the G4 examples included in `FlukaCern` with `FLUKA`,
0008 please directly follow the `README.md` files included in
0009 `ProcessLevel/CrossSection` and `ProcessLevel/FinalState`.
0010
0011
0012 # Description
0013
0014 The `FLUKA` hadron inelastic physics are accessible both through a `CrossSectionDataSet` and `HadronicInteraction`.
0015 The `CrossSectionDataSet` and `HadronicInteraction` can be used to define processes, themselves used to form a `FLUKAHadronInelasticPhysicsConstructor`.
0016 The `FLUKAHadronInelasticPhysicsConstructor` can in turn be used to form any `G4PhysicsList`. One example of `G4PhysicsList` is provided (initially `FTFP_BERT_HP`, but with hadron inelastic physics from `FLUKA` instead).
0017 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).
0018
0019
0020 # Structure
0021
0022 The project contains:
0023 - `fluka4_wrapper`: wrapper to `FLUKA`.
0024 - `cpp_fortran_bridges`: fortran <-> C++ interfacing tools.
0025 - `cpp_utils`: general project helpers (C++ string manipulation, etc).
0026 - `fluka5`: interface to `FLUKA` inelastic hadron-nucleus interactions.
0027 - `fluka_G4_physics_list`: `ModularPhysicsList`, `PhysicsConstructor`, `CrossSectionDataSet`, `HadronicInteraction` to make up a G4 physics list.
0028 - `fluka_G4_bridges`: conversion tools to switch between `FLUKA` and G4 worlds (particles, random numbers, etc).
0029
0030
0031 # Dependency
0032
0033 ### Environment
0034 - **gcc** >= 7 (Linux) and **gcc** >= 9 (MacOS)
0035 In practice, a recent version is recommended, at least `gcc >=10`.
0036 ```
0037 gcc --version
0038 ```
0039
0040 - **CMake** >= 3.16...3.21
0041 ```
0042 cmake3 --version
0043 ```
0044
0045 - **G4** >= 11.0.3 (Not tested on older G4 releases: might still work, but with no guarantee).
0046 IMPORTANT: YOU NEED TO SOURCE YOUR G4 ENVIRONMENT.
0047 It needs to be sourced in whichever terminal you want to build / run a G4 application with the `FLUKA` interface.
0048 ```
0049 source path_to_geant4/install/bin/geant4.sh
0050 which geant4-config   # NB: Your geant4-config should support the modern CMake way of building G4.
0051 ```
0052
0053 - **Easy setup on lxplus** (lxplus7):
0054 All you need to do on lxplus, to setup an environment satisfying all the conditions above, is, for example:
0055 ```
0056 source /cvmfs/sft.cern.ch/lcg/releases/gcc/10.1.0/x86_64-centos7/setup.sh
0057 source /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/CMake-setup.sh
0058 # NB: Your geant4.sh is at: /cvmfs/geant4.cern.ch/geant4/11.1/x86_64-centos7-gcc10-optdeb-MT/bin/geant4.sh
0059 ```
0060
0061 ### `FLUKA4`
0062 Release: >= **4-3.2**
0063
0064 Please install the latest `FLUKA` release.
0065 (1) You first need to register (and accept the licence when relevant): https://fluka.cern/download/registration
0066 (2) You can then download the `binary libraries` (or potentially the `source code` package, depending on your case):
0067 https://fluka.cern/download/latest-fluka-release.
0068 (3) Follow the `FLUKA` installation instructions: https://fluka.cern/documentation/installation
0069 In particular, for a Linux/MacOS install: https://fluka.cern/documentation/installation/fluka-linux-macos
0070 They will show you how to setup `FLUKA`.
0071 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`.
0072 (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.
0073 Do not forget to add `/path_to_fluka/bin` to your `PATH`. Check with `which fluka`.
0074
0075 ### `FlukaInterface`
0076 A version of the G4-FLUKA interface (`FLUKA` hadron-nucleus inelastic physics)
0077 is located at `geant4/examples/extended/hadronic/FlukaCern/FlukaInterface`.
0078 You will first need to build the interface to `FLUKA`, and create the environment scripts.
0079 ```bash
0080 $ cd geant4/examples/extended/hadronic/FlukaCern/FlukaInterface/
0081 # Check with `which fluka` that fluka executable is added to your `PATH`.
0082 $ source path_to_geant4/install/bin/geant4.sh
0083 $ make interface
0084 $ make env       # Creates `env_FLUKA.sh` and `env_FLUKA_G4_interface.sh`
0085 ```
0086 IMPORTANT: `env_FLUKA_G4_interface.sh` needs to be sourced in whichever terminal
0087 you want to compile / run a G4 application with the `FLUKA` interface.
0088
0089
0090 # Use as a FLUKA physics list (in ANY G4 application)
0091 Reminder: this is a generic guide to be able to use the `FLUKA` interface from *any* G4 application.
0092 If you are trying to build / run the G4 examples included in `FlukaCern` with `FLUKA`, you can directly follow the `README.md` files included in those examples.
0093 Notably, the file in `cmake/Modules` is already included in those examples (the rest of the procedure is the same).
0094
0095 ```bash
0096 $ cd G4_application
0097 ```
0098
0099 - Edit your G4 application's `CMakeLists.txt`:
0100 You need to add the `FLUKA` module dependency. You need to add the following (for example, after the `project` line):
0101 ```bash
0102 #----------------------------------------------------------------------------
0103 # FindFLUKAInterface.cmake is located at your_path_to_geant4/cmake/Modules/FindFLUKAInterface.cmake
0104 # Check that FindFLUKAInterface.cmake can be found from $CMAKE_MODULE_PATH
0105 message(STATUS "CMAKE_MODULE_PATH = ${CMAKE_MODULE_PATH}")
0106 # Otherwise, you can always prepend it to the cmake module search path with:
0107 # set(CMAKE_MODULE_PATH my_path_to_find_fluka ${CMAKE_MODULE_PATH})
0108
0109 #----------------------------------------------------------------------------
0110 # Check whether FLUKA should be used or not
0111 set(G4_USE_FLUKA OFF CACHE BOOL "Using FLUKA")
0112 if(G4_USE_FLUKA)
0113   message(STATUS "G4_USE_FLUKA=ON : Using FLUKA interface for building ${PROJECT_SOURCE_DIR}")
0114   add_definitions(-DG4_USE_FLUKA)
0115   find_package(FLUKAInterface REQUIRED)
0116   if(FLUKAInterface_FOUND)
0117     message(STATUS "FLUKA cmake module was found : ${CMAKE_MODULE_PATH}")
0118   else()
0119     message(FATAL_ERROR "FLUKA cmake module was NOT found! Please add one.")
0120   endif()
0121 else()
0122   message(STATUS "G4_USE_FLUKA=OFF : NOT using FLUKA interface for building ${PROJECT_SOURCE_DIR}. \n \
0123   If ever you want to use the FLUKA interface, please repeat cmake command with -DG4_USE_FLUKA=1")
0124 endif()
0125 ```
0126 Additionally, add:
0127 `${FLUKAInterface_INCLUDE_DIR}` to the `include_directories` line.
0128 `${FLUKAInterface_LIBRARIES}` to the `target_link_libraries` line.
0129
0130 - You can now compile and run your G4 application:
0131 ```bash
0132 # Check with `which fluka` that fluka executable is added to your `PATH`.
0133 $ source path_to_geant4/install/bin/geant4.sh
0134 $ source path_to_FlukaInterface/env_FLUKA_G4_interface.sh             # Carefully follow the setup instructions if anything fails.
0135 $ cd build
0136 $ cmake3 -DGeant4_DIR=your_path_to_geant4 -DG4_USE_FLUKA=1 ../
0137 $ make -j8
0138 $ ./G4_executable
0139 ```
0140