diff --git a/CMakeLists.txt b/CMakeLists.txt index ef9a793..7d85f46 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,100 +1,108 @@ # Top level CMakeLists.txt for EvtGen # Enforce an out-of-source build. # Should be the first action in the top level CMakeLists.txt if(${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR}) message(STATUS "EvtGen requires an out-of-source build.") message(STATUS "Please remove the following files from ${CMAKE_BINARY_DIR}:") message(STATUS " CMakeCache.txt") message(STATUS " CMakeFiles") message(STATUS "Once these files are removed, create a separate directory") message(STATUS "and run CMake from there, pointing it to:") message(STATUS " ${CMAKE_SOURCE_DIR}") message(FATAL_ERROR "in-source build detected") endif() # Also require a minimum version of CMake cmake_minimum_required(VERSION 3.8.0) # Project setup if(${CMAKE_VERSION} VERSION_LESS 3.9.0) project(EvtGen VERSION 2.0.0 ) elseif(${CMAKE_VERSION} VERSION_LESS 3.12.0) project(EvtGen VERSION 2.0.0 DESCRIPTION "Monte Carlo generator of particle decays, in particular the weak decays of heavy flavour particles such as B mesons." ) else() project(EvtGen VERSION 2.0.0 DESCRIPTION "Monte Carlo generator of particle decays, in particular the weak decays of heavy flavour particles such as B mesons." HOMEPAGE_URL "https://evtgen.hepforge.org" ) endif() # Prepend this project's custom module path(s) to CMAKE_MODULE_PATH set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake/Modules ${CMAKE_MODULE_PATH}) # Include needed modules to perform any custom setup # Install paths include(GNUInstallDirs) # Compilation/linking flags and related settings include(CompilerFlags) # EvtGen external dependencies option(EVTGEN_PYTHIA "Enable/disable linking with Pythia8" OFF) option(EVTGEN_PHOTOS "Enable/disable linking with Photos++" OFF) option(EVTGEN_TAUOLA "Enable/disable linking with Tauola++" OFF) message(STATUS "EvtGen: Linking with HepMC2") message(STATUS "EvtGen: Optional linking with Pythia8 ${EVTGEN_PYTHIA}") message(STATUS "EvtGen: Optional linking with Photos++ ${EVTGEN_PHOTOS}") message(STATUS "EvtGen: Optional linking with Tauola++ ${EVTGEN_TAUOLA}") include(ExternalDependencies) # Now build the library add_subdirectory(src) # Copy the particle property and decay tables configure_file(DECAY.DEC ${CMAKE_CURRENT_BINARY_DIR}/DECAY.DEC COPYONLY) configure_file(DECAY.XML ${CMAKE_CURRENT_BINARY_DIR}/DECAY.XML COPYONLY) configure_file(evt.pdl ${CMAKE_CURRENT_BINARY_DIR}/evt.pdl COPYONLY) # Build the executables in the test and validation directories -add_subdirectory(test) -add_subdirectory(validation) +option(EVTGEN_BUILD_TESTS "Enable/disable building of executables in 'test' directory" OFF) +option(EVTGEN_BUILD_VALIDATIONS "Enable/disable building of executables in 'validation' directory" OFF) +message(STATUS "EvtGen: Building of executables in 'test' directory ${EVTGEN_BUILD_TESTS}") +message(STATUS "EvtGen: Building of executables in 'validation' directory ${EVTGEN_BUILD_VALIDATIONS}") +if(${EVTGEN_BUILD_TESTS}) + add_subdirectory(test) +endif() +if(${EVTGEN_BUILD_VALIDATIONS}) + add_subdirectory(validation) +endif() # Install the include directories -install(DIRECTORY EvtGen DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) -install(DIRECTORY EvtGenBase DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) +install(DIRECTORY EvtGen DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) +install(DIRECTORY EvtGenBase DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) install(DIRECTORY EvtGenExternal DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) -install(DIRECTORY EvtGenModels DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) +install(DIRECTORY EvtGenModels DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # Install the particle properties and decay tables install(FILES DECAY.DEC DECAY.XML evt.pdl DESTINATION ${CMAKE_INSTALL_PREFIX}) # Generate CMake config files, which can be used by other projects include(CMakePackageConfigHelpers) set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}) set(LIB_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR}) configure_package_config_file(cmake/Templates/EvtGenConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/EvtGenConfig.cmake INSTALL_DESTINATION cmake PATH_VARS INCLUDE_INSTALL_DIR LIB_INSTALL_DIR ) write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/EvtGenConfigVersion.cmake COMPATIBILITY AnyNewerVersion ) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/EvtGenConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/EvtGenConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_PREFIX}/cmake ) install( EXPORT "EvtGenTargets" NAMESPACE "EvtGen::" DESTINATION ${CMAKE_INSTALL_PREFIX}/cmake ) diff --git a/README b/README index 5a1fc05..42bdf15 100644 --- a/README +++ b/README @@ -1,195 +1,198 @@ RELEASE NOTES ============= Please see History.txt for a detailed list of changes to this package. The major points comparing this version with the 2009 release are the following: 1. This version requires HepMC (version 2.04 and above) for storing event structures of particle decays, and can also use Pythia 8 (version 8.180 and above is required) and the C++ interfaced packages Photos (version 3.5.2 and above) and Tauola (version 1.0.7 and above). These external generators are included via engine classes in the new sub-directory EvtGenExternal. Two libraries can be created for EvtGen: i) libEvtGen.so contains the EvtGenBase and EvtGenModel core code/decay models, ii) libEvtGenExternal.so contains _only_ the code within EvtGenExternal. This means that the external generator interface can be ignored by not loading/creating the 2nd library libEvtGenExternal.so. In the installation instructions below, it is possible to select which external generators you want to use. Note, however, that the generic "DECAY.DEC" file contains Pythia decays, and if Pythia is not included in the build, these decays are not generated (in fact, they would need a new decay model specified). Likewise, if Photos is not included, there will be no radiative corrections done for particle decays. To use the external generators, use the following code: #include "EvtGenExternal/EvtExternalGenList.hh" #include "EvtGenBase/EvtAbsRadCorr.hh" #include "EvtGenBase/EvtDecayBase.hh" // Set up the default external generator list: Photos, Pythia and/or Tauola EvtExternalGenList genList; EvtAbsRadCorr* radCorrEngine = genList.getPhotosModel(); std::list extraModels = genList.getListOfModels(); // Create the EvtGen generator object EvtGen myGenerator("decayFile.dec", "evt.pdl", randomEnginePointer, radCorrEngine, &extraModels); //If you don't want to use external generators, use the following: //EvtGen myGenerator("decayFile.dec", "evt.pdl", randomEnginePointer); The files Pythia8_README.txt and Tauola_README.txt have more details about using the new Pythia 8 and Tauola generators (called via the PYTHIA and TAUOLA "decay.dec" model names). The new Photos generator is still called via the PHOTOS "decay.dec" model name. It is now possible to use alias particle decays for the Pythia 8 model. Two Pythia 8 instances are used in EvtPythiaEngine for normal and aliased decays. Since the underlying code for Photos and Tauola is still Fortran, it is only possible to have one (unique) instance of each of these external generators. This can only be fixed if these packages are converted to pure C++ code. 2. This version of EvtGen is effectively a merger of the latest LHCb and BaBar EvtGenBase and EvtGenModels code. Various decay models have been added, and there have been a range of bug fixes. 3. There is also a new Dalitz decay class model "GENERIC_DALITZ" (EvtGenModels/EvtGenericDalitz.cpp), that should be used instead of EvtDDalitz. The generic Dalitz model uses xml files to configure the resonance amplitude parameters (instead of being hardcoded in EvtDDalitz): Decay D+ 1.0 K- pi+ pi+ GENERIC_DALITZ MyDalitzParameters.xml; Enddecay Examples of xml Dalitz parameter files are given in the sub-directory validation/DalitzFiles, e.g. see DalitzDecays.xml. 4. It is possible to use decay files in xml format. Use the python script convertDecayFile.py for converting decay files to the new format. The src/EvtGen.cpp constructor has an additional boolean argument useXml that needs to be set to true if xml decay files are to be used (default is useXml=false). For example, DECAY_2010.XML is the xml version of DECAY_2010.DEC. 5. Bug fixes for Bs mixing decay/CP violation amplitudes. Added the capability to use either coherent or incoherent mixing in EvtCPUtil. One or the other can be chosen as the mixing method for the B system by choosing 0 (coherent) or 1 (incoherent) for the last integer argument in the EvtGen() constructor. BUILDING THE CODE ================= To build the EvtGen code, first make sure that there is a valid (C++) version of HepMC avilable: HepMC http://hepmc.web.cern.ch//hepmc/ HepMC is used to store particle information. Optionally, it is possible to use other external generators, such as Pythia8 (for Pythia decays in the DECAY.DEC file, for example), Photos (for radiative corrections) and Tauola (for tau decays): Pythia8 http://home.thep.lu.se/~torbjorn/Pythia.html Photos http://photospp.web.cern.ch/photospp/ Tauola http://tauolapp.web.cern.ch/tauolapp/ All of these packages have instructions for building them. Once these packages are available, build the EvtGen release by creating a build directory alongside the EvtGen source directory (assumed here to be called evtgen.git) and running: cmake ../evtgen.git within the EvtGen build directory, using the following options: - -DCMAKE_INSTALL_PREFIX= : Location in which to install EvtGen (optional but - highly recommended) + -DCMAKE_INSTALL_PREFIX= : Location in which to install EvtGen (highly recommended) - -DHEPMC2_ROOT_DIR= : Location of HepMC install directory (optional) - While HepMC is mandatory, depending on your - environment the installation may be detected + -DHEPMC2_ROOT_DIR= : Location of HepMC install directory + While linking with HepMC is mandatory, depending on + your environment the installation may be detected automatically. Failing this, you can specify the location via this option. - -DEVTGEN_PYTHIA=ON : Enable linking with Pythia 8 (optional) - -DPYTHIA8_ROOT_DIR= : Location of Pythia8 install directory (optional) + -DEVTGEN_PYTHIA=ON : Enable linking with Pythia 8 + -DPYTHIA8_ROOT_DIR= : Location of Pythia8 install directory As with HepMC this may be automatically detected depending on your build environment, otherwise the location can be specified via this option. - -DEVTGEN_PHOTOS=ON : Enable linking with Photos++ (optional) - -DPHOTOSPP_ROOT_DIR= : Location of Photos++ install directory (optional) + -DEVTGEN_PHOTOS=ON : Enable linking with Photos++ + -DPHOTOSPP_ROOT_DIR= : Location of Photos++ install directory As with HepMC this may be automatically detected depending on your build environment, otherwise the location can be specified via this option. - -DEVTGEN_TAUOLA=ON : Enable linking with Tauola++ (optional) - -DTAUOLAPP_ROOT_DIR= : Location of Tauola++ install directory (optional) + -DEVTGEN_TAUOLA=ON : Enable linking with Tauola++ + -DTAUOLAPP_ROOT_DIR= : Location of Tauola++ install directory As with HepMC this may be automatically detected depending on your build environment, otherwise the location can be specified via this option. + -DEVTGEN_BUILD_TESTS=ON : Enable building executables in 'test' directory + + -DEVTGEN_BUILD_VALIDATIONS=ON : Enable building executables in 'validation' directory + Then compile and (optionally, although highly recommended) install the EvtGen code using make make install This should create the libraries lib/libEvtGen.so and lib/libEvtGenExternal.so, as well as the archives lib/archive/libEvtGen.a and lib/archive/libEvtGenExternal.a (the "EvtGenExternal" library/archive will not be created if linking is not enabled for any of the external generators). A series of validation and test executables are also created (discussed below). The CMakeLists.txt file in these two directories can be used as a template for building any user executables. The build/install will also create CMake config files that allow the library targets to be easily imported into other projects. To use Pythia 8, the environment variable PYTHIA8DATA needs to be set to the location of the corresponding xml documentation directory, which also contains the default values for particle decays and models: /xmldoc Code validation =============== The validation sub-directory contains code validation test cases for Pythia, Tauola and B mixing models. Note that these executables also depend on ROOT, which is only used to create ntuples and plots for the validation examples. The script genAllDecayExamples.sh runs other scripts that generate a range of decay modes using the genExampleRootFiles.cc program. The script compareAllDecays.sh runs a range of scripts that creates comparison plots using the compareRootFiles.cc program. For now, the comparisons use the same plots, but each of the "compare.sh" files can be edited to compare any two versions of ROOT data created by the genExampleRootFiles.cc program. The testCPVDecays.cc program runs a test for the B mixing decay model. Examples ======== Some examples are provided in the test sub-directory. Note that these executables also depend on ROOT, which is only used to create ntuples and plots for the validation examples. Running the script "./do_tests" will run a series of EvtGen examples. Example decay files are in the test/exampleFiles sub-directory.