Chapter 2
Installation and directories

2.1 Installation

The external requirements for (CuTe-)MCFM are cmake (>= 3.13) and gcc/g++/gfortran (>= 7).

Optional external dependencies are LHAPDF (6.2.X or 6.5.X) and an MPI implementation (we recommend OpenMPI) or Coarrays implementation

By default MCFM is bundled with LHAPDF 6.5.1. It can optionally be compiled with an external LHAPDF installation. Note that LHAPDF 6.3.X has a multithreading bug and therefore we do not recommend to use it. Either use LHAPDF 6.2.X or 6.5.X. Version 5 of LHAPDF is not supported.

The MCFM package may be downloaded from the MCFM homepage at https://mcfm.fnal.gov. After extracting, in the simplest case, the source can be compiled by running cmake .. in the Bin directory: 

  tar -xzvf MCFM-X.Y.tar.gz
  cd MCFM-X.Y/Bin

To compile with default options just run cmake .. in the Bin directory or a new “build” directory, then run make to compile the MCFM program. If you compile in a directory different than “Bin”, please run make install to copy some required files over from the Bin directory. The Bin directory contains several example input files that can be used as an argument to mcfm.

By default all necessary dependencies, including LHAPDF, are compiled with the default compiler that cmake detects. The following parameters can be added to choose a custom compiler. For example with MPI the wrapper mpifort will have to be chosen as the Fortran compiler: 

  -DCMAKE_C_COMPILER=gcc-8
  -DCMAKE_CXX_COMPILER=g++-8
  -DCMAKE_Fortran_COMPILER=gfortran-8

Please ensure that your compiler is working and can produce executable program files. Please also ensure that it is at least version 7 (e.g. gfortran –version). For example when your compiler has been installed into a non-standard location you probably need to append the compiler library path to LD_LIBRARY_PATH (DYLD_FALLBACK_LIBRARY_PATH on OS X). This can be achieved, for example, as follows: 

  export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/home/user/local/lib/gcc7

Additional complications may arise especially on OS X systems, where by default gcc/g++ is linked to the clang compiler. Please make sure to set the compiler names/paths to the correct GNU versions.

If CMake does not report any problems you can start the compilation of MCFM with make -j4, where 4 (or more) is the number of compilation threads.

Upon successful compilation, the executable mcfm is produced and can be called with an input file (+path) as argument, for example: 

       ./mcfm input_Z.ini

It can happen that the CMake cache gets corrupted with wrong configuration options. If you change options and errors occur, please try to delete the file CMakeCache.txt and directory CMakeFiles and restart cmake .. with the appropriate arguments.

2.1.1 Compiling at Fermilab

To compile at Fermilab on the Wilson cluster (wc.fnal.gov): 

 cd MCFM-10.3/Bin/
 cmake -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++  ..
 make -j

2.1.2 Compiling at CERN

On the lxplus machine at CERN (lxplus.cern.ch): 

 cd MCFM-10.3/Bin/
 cmake3 -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++  ..
 make -j

It is also necessary to use 

 export OMP_STACKSIZE=16000

in the Bash shell (and similar for other shells), as discussed below.

2.1.3 LHAPDF

The following parameter specifies the use of LHAPDF (internal, external): 

  -Duse_internal_lhapdf=ON (default)

and can be set to OFF to link against an external LHAPDF library.

When an external LHAPDF is used, cmake might not find the library. A library search path can be added with -DCMAKE_PREFIX_PATH=/usr/local, for example. Additionally, the LHAPDF include path can be set with -Dlhapdf_include_path=/usr/local/include if it deviates from a standard location.

For the bundled LHAPDF, PDF sets go into the directory Bin/PDFs. This installation includes the central PDF members of CT18NNLO and NNPDF31_nnlo_as_0118 with their resummation grids, as well as the PDF sets for LUXqed17_plus_PDF4LHC15_nnlo_30. Additional PDFs can be downloaded from https://lhapdf.hepforge.org/pdfsets.html and untar’ed in the PDFs directory.

Additional PDF directories can be added to the LHAPDF search path by using, for example: 

  export LHAPDF_DATA_PATH=/usr/local/share/LHAPDF

2.1.4 WW, WZ and ZZ with VVamp

The processes WW,WZ and ZZ at NNLO require compilation of the VVamp amplitudes, which are about 100MB of additional sourcecode and add significant additional compilation time. The following flag disables these amplitudes: 

  -Dwith_vvamp=OFF

2.1.5 OpenMP and MPI

MCFM uses OMP (Open Multi-Processing) to implement multi-threading and automatically adjusts to the number of available CPU threads. The multi-threading is implemented with respect to the integration routine Vegas, which distributes the event evaluations over the threads and combines all events at the end of every iteration.

Two environment variables are useful. On some systems, depending on the OMP implementation, the program will crash when calculating some of the more complicated processes, for example W + 2 jet production at NLO. Then, adjusting OMP_STACKSIZE may be needed for the program to run correctly. Setting this variable to 16000, for instance in the Bash shell by using the command export OMP_STACKSIZE=16000, has been found to be sufficient for all processes. The second useful variable OMP_NUM_THREADS may be used to directly control the number of threads used during OMP execution (the default is the maximum number of threads available on the system).

To prepare MCFM with MPI support add the argument -Duse_mpi=ON to the cmake call before running make.. At the same time custom compiler command names must be specified with: 

  -DCMAKE_C_COMPILER=mpicc
  -DCMAKE_CXX_COMPILER=mpic++
  -DCMAKE_Fortran_COMPILER=mpifort

Such commands must be used when compiling with MPI support and their names can depend on the MPI implementation. Please consult the manual of your MPI installation or cluster system. Please ensure again that mpifort –version and mpic++ –version report the GNU compiler and a version greater than 7.

Alternatively also a Fortran Coarray implementation can be used with: 

  -Duse_coarray=ON

This option is experimental and cannot be used together with MPI.

2.2 Directory structure

The directory structure of MCFM is as follows:

2.3 References

The program has been developed over a number of years and results have been presented in a number of published papers. The papers describing the original code and the most significant developments in the NLO implementation are:

As of v8.0 MCFM can also compute selected color-singlet processes through NNLO in QCD perturbation theory. The processes available at this precision, as well as benchmark numbers, are detailed in Section 8. When using MCFM 8.0 or newer for NNLO calculations please refer to:

A significant overhaul of MCFM was undertaken in v9.0 of MCFM. If you use this version or newer please cite

Version 10.0 includes SCET-based qT resummation and is called CuTe-MCFM when this feature is used. When you use the qT resummation please cite

The manual for the resummation functionality can be found in cute-mcfm.pdf.

Version 10.1 includes a C++ interface to many of the 1-loop matrix elements included in the code. When you use this functionality please cite

A guide to the structure of the interface is included in this paper.

Version 10.2 includes a more complete treatment of color singlet production processes at NNLO, expecially colour singlet processes involving pairs of bosons.