LHAPDF is the standard tool for evaluating parton distribution functions (PDFs) in high-energy physics. PDFs encode the flavour and momentum structure of composite particles, such as protons, pions and nuclei; most cross-section calculations are based on parton-level matrix-elements which must be connected to the real interacting particles, hence PDFs are an essential ingredient of phenomenological and experimental studies at hadron and heavy-ion colliders (e.g. LHC, HERA, Tevatron, EIC, FCC) and in cosmic-ray physics.
PDFs themselves are fitted to a range of data by various collaborations. LHAPDF provides the definitive community library of such fits, in a standard data-format, as well as C++ and Python interfaces for evaluating them. Written as a general purpose C++ interpolator for estimating PDFs from discretised data files, it has also found more general uses, such as for fragmentation functions (essentially the inverse of PDFs).
Previous versions of LHAPDF were written in Fortran 77/90 and are documented at http://lhapdf.hepforge.org/lhapdf5/ . LHAPDF6 vastly reduces the memory overhead of the Fortran LHAPDF (from gigabytes to megabytes!), entirely removes restrictions on numbers of concurrent PDFs, allows access to single PDF members without needing to load whole sets, and separates a new standardised PDF data format from the code library so that new PDF sets may be created and released easier and faster. The C++ LHAPDF6 also permits arbitrary parton contents via the standard PDG ID code scheme, is computationally more efficient (particularly if only one or two flavours are required at each phase space point, as in PDF reweighting), and uses a flexible metadata system which fixes many fundamental metadata and concurrency bugs in LHAPDF5.
Compatibility routines are provided as standard for existing C++ and Fortran codes using the LHAPDF5 and PDFLIB legacy interfaces, so you can keep using your existing codes. But the new interface is much more powerful and pleasant to work with, so we think you'll want to switch once you've used it!
LHAPDF6 is documented in more detail in http://arxiv.org/abs/1412.7420
The source files can be downloaded from https://lhapdf.hepforge.org/downloads/
Full installation and troubleshooting details are given at Installation instructions .
The following link takes you to the PDF sets which are currently available and officially supported:
The PDF set data files can be downloaded from http://lhapdfsets.web.cern.ch/lhapdfsets/current/ which is also available via CERN CVMFS at
/cvmfs/sft.cern.ch/lcg/external/lhapdfsets/current/. Many users will find it easiest to just set their
LHAPDF_DATA_PATH environment variable to point at this distributed filesystem area and use the preinstalled latest sets there.
We also provide a script called
lhapdf which can be used to query the catalogue of PDF sets and to install and update them from the command line. The user interface of this script is inspired by the Debian Linux
apt package management system – it accepts commands
upgrade. Please run
lhapdf help for full usage instructions. Please note that this script currently requires the LHAPDF library to have been built and installed with Python support.
The most recent PDF set families of each major PDF fitting group from LHAPDF5 were migrated to the unified LHAPDF6 format. With a few exceptions for particularly significant older PDF sets, this means an effective age cutoff of ~2005 on the migrated sets.
If you need older sets you are encouraged to convert the LHAPDF5 version to LHAPDF6's data format: see the Instructions for building and running migration scripts/programs page for details of this procedure. We do not provide support for LHAPDF5, and a very strong case will be needed for further "official" set migrations beyond the many already available in LHAPDF6.
If you want to add new PDF sets (or fragmentation functions, etc.) to the standard collection, or update existing data files, please create a new GitLab issue at https://gitlab.com/hepcedar/lhapdf/-/issues , with the "PDF data" label.
Note that you are expected to create and validate these data files yourself, and to fix and update them in the case of user-reported bugs in the public files. We will allocate appropriate ID codes (which need to be added to your new sets'
.info files) and manage the indexing and distribution of the new files. We reserve the right to not incorporate PDFs unsuitable for public use.
Please follow this process to make the submission as smooth as possible:
For new sets, in the first instance please just describe the PDFs to be added, including the number of members for each set: we will then propose LHAPDF ID codes for each set. Do not attach the set tarballs to the issue, as they will definitely need an update before they can be used.
For updates you can go directly to the next step.
SetIndexflag in its
.infofile, and set the
1if a new release, otherwise increment by one.
.tar.gzextension such that it will expand to the set directory (and its contents) only:
tar czf MySet.tar.gz MySet/.
If you encounter any issues or have queries about some aspect, please discuss on the merge-request ticket, or contact the LHAPDF authors at firstname.lastname@example.org@m.pport.nosp@m.@email@example.com .
As for previous versions, LHAPDF6 is a programmatic library. It can be accessed via user code written in C++, and to a more limited extent from Python and Fortran programs.
PDF sets (each of which is stored in a unique filesystem directory) should usually be installed in the
$prefix/share/LHAPDF/ directory (i.e. the PDF dirs are at the same level as the global
lhapdf.conf file). To make use of PDF sets installed in other places, those search paths should be listed in the
LHAPDF_DATA_PATH environment variable. [
LHAPDF_DATA_PATH is an extension of the old
LHAPATH variable which supports multiple search paths separated by colon (
:) characters, cf. standard system paths like
Here are some reference documents on the library design and the system of PDF/set/config metadata flags:
Many code usage examples are collected here:
Using LHAPDF through Python just requires that the LHAPDF library and module be installed, then you can use it: there are no compilation or linking complexities, provided the Python and dynamic-library search paths are correctly set up.
For C++ and Fortran, however, you need to compile your code against LHAPDF, which introduces some extra technical hurdles.
Building your own program that uses LHAPDF6 is aided by the
lhapdf-config script which can among other things produce the compiler flags needed to use LHAPDF. These include the
-I/path/to/include flag to indicate the position of installed LHAPDF header files, and
-L/path/to/lib -lLHAPDF flags for the library linker. The script is used in a compilation/linking command like this:
g++ mycode.cc -o myexe `lhapdf-config --cflags --ldflags`
If you are compiling a Fortran program against LHAPDF, the header files are not relevant, but the library details are. You will also need to explicitly link against the C++ standard library, which is done implicitly by C++ compilers:
gfortran mycode.f90 -o myexe `lhapdf-config --ldflags` -lstdc++
Finally, note that LHAPDF is primarily available as a "dynamic" shared library, i.e. a
.dylib (Mac) rather than a static
.a library. The dynamic library needs to be found at runtime as well as at compile/link time.
If your code compiled fine, but you get errors about "missing symbol" when you try to run your program, you probably need to add the LHAPDF lib directory path to your
LD_LIBRARY_PATH environment variable (or
DYLD_LIBRARY_PATH on Macs):
A typical LHAPDF6 PDF set with error members is between 20 and 100 MB in size. If you only intend to use a subset of these (e.g. in MC production where you will only use the central member), you can simply remove the unneeded
.dat files from the PDF set directory. It will work fine, as long as you don't try to load one of the missing members of course! In grid job submissions this can reduce the tarball of data that you send with your job by a large amount, since PDF sets often dominate such job tarballs.
For special applications where PDF initialization speed or disk space are very critical, you may wish to use zipped PDF data files. Since the data files are plain text, they compress well, by a factor of 4 or so, but for most applications this is largely irrelevant since you will usually not need to install more than about 100 MB of data files to use the main modern PDF sets, and set initialisation time is less than one second... and that happens only once per run.
Actually reading zipped data files would make LHAPDF's code and (more importantly) build process much more awkward, so we haven't done that. However, if you really need to squeeze the maximum out of limited space and time then there is a trick you can play – at least on Linux systems – using
LD_PRELOAD. This environment variable specifies libraries to be loaded before starting a process, and is a mechanism for replacing system library functions with modified versions.
In this case, we can override the
open("foo") function with a version which will attempt to transparently read
foo.gz, uncompressed into the
/tmp directory, by setting
LD_PRELOAD=/lib/uncompress.so in your job. See the zlibc documentation for more details. LHAPDF6 itself needs no modification, but you will need to
cd into your PDF sets and run
for i in *.dat; do gzip $i; done in each one that you want to compress.
This is rather a hack and may not work on Macs... but it can be useful in special circumstances. Please let us know your experiences if you use it!
If you need assistance with LHAPDF, please contact the authors at firstname.lastname@example.org@m.pport.nosp@m.@email@example.com . Please also send feature suggestions to this address: please don't contact individual developers if you can avoid it. We also accept compliments ;-)
You are very strongly advised to make sure that you are running the latest version of the LHAPDF library, since issues are often fixed in later releases. Please supply information about which version you are using, what type of system and compiler you are using, a copy of the LHAPDF config.log file, a reasonably full copy of the errors you are getting, and the output of downloading and running this script: https://users.hepforge.org/~buckley/sysdebug.sh .
Please do not send us screenshots of your terminal! To capture the output of a command, use a shell redirection like this:
make &> makelog.txt or
bash sysdebug.sh &> sysdebug.txt (you may prefer to use a redirection like
|& tee foolog.txt but probably you don't need our advice if you have such preferences.)
Lastly, please try to read the configure/compiler/runtime error message: once decoded it may tell you something simple e.g. you have not got the required compiler, you are compiling against a 32 bit library on a 64 bit system, or you have not installed a PDF data file. If you can't parse the error messages then try Googling for generic-looking bits of the message before asking for direct assistance: there are often good explanations and solutions online.
To check out LHAPDF6 from git, visit the GitLab page below and follow the clone instructions, either via SSH or HTTPS.
See the following pages: