FlukaCern/FlukaInterface/README.md

0001 \page ModuleFlukaInterface Module FlukaInterface
0002
0003 # Interface to `FLUKA` physics models
0004
0005 This is an interface to the `FLUKA` CERN hadron inelastic physics.
0006 It can be used by ANY G4 application (including the experimental frameworks, provided they are relying on G4 physics lists already).
0007
0008 Note that this is a generic guide to be able to use the `FLUKA` interface from *any* G4 application.
0009 If you are trying to build / run the G4 examples included in `FlukaCern` with `FLUKA`,
0010 please directly follow the `README.md` files included in
0011 `ProcessLevel/CrossSection` and `ProcessLevel/FinalState`.
0012
0013
0014 ## Description
0015
0016 The `FLUKA` hadron inelastic physics are accessible both through a `CrossSectionDataSet` and `HadronicInteraction`.
0017 The `CrossSectionDataSet` and `HadronicInteraction` can be used to define processes, themselves used to form a `FLUKAHadronInelasticPhysicsConstructor`.
0018 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).
0019 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).
0020
0021
0022 ## Structure
0023
0024 The project contains:
0025 - `fluka4_wrapper`: wrapper to `FLUKA`.
0026 - `cpp_fortran_bridges`: fortran <-> C++ interfacing tools.
0027 - `cpp_utils`: general project helpers (C++ string manipulation, etc).
0028 - `fluka5`: interface to `FLUKA` inelastic hadron-nucleus interactions.
0029 - `fluka_G4_physics_list`: `ModularPhysicsList`, `PhysicsConstructor`, `CrossSectionDataSet`, `HadronicInteraction` to make up a G4 physics list.
0030 - `fluka_G4_bridges`: conversion tools to switch between `FLUKA` and G4 worlds (particles, random numbers, etc).
0031
0032
0033 ## Dependency
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 compile / run a G4 application with the `FLUKA` interface.
0090
0091
0092 ## Use as a FLUKA physics list (in ANY G4 application)
0093 Reminder: this is a generic guide to be able to use the `FLUKA` interface from *any* G4 application.
0094 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.
0095 Notably, the file in `cmake/Modules` is already included in those examples (the rest of the procedure is the same).
0096
0097 ```bash
0098 $ cd G4_application
0099 ```
0100
0101 - Edit your G4 application's `CMakeLists.txt`:
0102 You need to add the `FLUKA` module dependency. You need to add the following (for example, after the `project` line):
0103 ```bash
0104 #----------------------------------------------------------------------------
0105 # FindFLUKAInterface.cmake is located at your_path_to_geant4/cmake/Modules/FindFLUKAInterface.cmake
0106 # Check that FindFLUKAInterface.cmake can be found from $CMAKE_MODULE_PATH
0107 message(STATUS "CMAKE_MODULE_PATH = ${CMAKE_MODULE_PATH}")
0108 # Otherwise, you can always prepend it to the cmake module search path with:
0109 # set(CMAKE_MODULE_PATH my_path_to_find_fluka ${CMAKE_MODULE_PATH})
0110
0111 #----------------------------------------------------------------------------
0112 # Check whether FLUKA should be used or not
0113 set(G4_USE_FLUKA OFF CACHE BOOL "Using FLUKA")
0114 if(G4_USE_FLUKA)
0115   message(STATUS "G4_USE_FLUKA=ON : Using FLUKA interface for building ${PROJECT_SOURCE_DIR}")
0116   add_definitions(-DG4_USE_FLUKA)
0117   find_package(FLUKAInterface REQUIRED)
0118   if(FLUKAInterface_FOUND)
0119     message(STATUS "FLUKA cmake module was found : ${CMAKE_MODULE_PATH}")
0120   else()
0121     message(FATAL_ERROR "FLUKA cmake module was NOT found! Please add one.")
0122   endif()
0123 else()
0124   message(STATUS "G4_USE_FLUKA=OFF : NOT using FLUKA interface for building ${PROJECT_SOURCE_DIR}. \n \
0125   If ever you want to use the FLUKA interface, please repeat cmake command with -DG4_USE_FLUKA=1")
0126 endif()
0127 ```
0128 Additionally, add:
0129 `${FLUKAInterface_INCLUDE_DIR}` to the `include_directories` line.
0130 `${FLUKAInterface_LIBRARIES}` to the `target_link_libraries` line.
0131
0132 - You can now compile and run your G4 application:
0133 ```bash
0134 # Check with `which fluka` that fluka executable is added to your `PATH`.
0135 $ source path_to_geant4/install/bin/geant4.sh
0136 $ source path_to_FlukaInterface/env_FLUKA_G4_interface.sh             # Carefully follow the setup instructions if anything fails.
0137 $ cd build
0138 $ cmake3 -DGeant4_DIR=your_path_to_geant4 -DG4_USE_FLUKA=1 ../
0139 $ make -j8
0140 $ ./G4_executable
0141 ```
0142