Introduction

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).

History and compatibility

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

Installation

The source files can be downloaded from https://lhapdf.hepforge.org/downloads/

Full installation and troubleshooting details are given at Installation instructions .

Official PDF sets

The following link takes you to the PDF sets which are currently available and officially supported:

PDF sets

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 list, update, install and 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.

Submitting new PDF sets

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.
Prepare the tarballs for integration:
- Assign these ID codes to each PDF set's SetIndex flag in its .info file, and set the DataVersion flag to 1 if a new release, otherwise increment by one.
- Ensure the Unix file permissions are 755 for the set directories, and 644 for the data files within.
- Make sure there are no extraneous files (e.g. Mac .DS_Store hidden directories).
- Make each tarball with a .tar.gz extension such that it will expand to the set directory (and its contents) only: tar czf MySet.tar.gz MySet/ .
- Place the tarballs in a directly downloadable Web location – avoid services which require browser authentication or will download with a mangled filename: the sync will be performed with a command-line retrieval tool like wget or curl.
Notify the set of download URLs on the GitLab issue.

If you encounter any issues or have queries about some aspect, please discuss on the merge-request ticket, or contact the LHAPDF authors at lhapd.nosp@m.f-su.nosp@m.pport.nosp@m.@cer.nosp@m.n.ch .

Usage

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 PATH, LD_LIBRARY_PATH, etc.]

Here are some reference documents on the library design and the system of PDF/set/config metadata flags:

Design rationale: Design
PDF metadata flags: Configuration flags

Many code usage examples are collected here:

Code examples: Code examples

Warning: Note that from the 6.5.x release series onwards, LHAPDF is fully thread-safe. To ensure this, several elements which could previously live in shared memory between threads – sometimes creating race conditions, and generally risking cross-thread corruption – are now explicitly thread-local. In particular, note that in the Fortran interface it is now essential to call the initialization routines for your PDF sets on every thread, not just one.

Building against LHAPDF

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++

Runtime symbol resolution

Finally, note that LHAPDF is primarily available as a "dynamic" shared library, i.e. a .so or .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):

export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH

Trick to remove unwanted PDF members

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.

Trick to use zipped data files

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!

Authors

LHAPDF6 AUTHORS
===============
 
Lead developer:
  Andy Buckley
 
Code contributors:
  James Ferrando
  David Hall
  Max Knobbe
  Steve Lloyd
  Karl Nordstrom
  Martin Ruefenacht
  Graeme Watt
 
Testing, advice, data management, etc.:
  Richard Ball
  Luigi del Debbio
  Nathan Hartland
  Dmitri Konstantinov
  Ben Page
  Juan Rojo
  Marek Schoenherr
  Mike Whalley
 
 
CITATION
========
 
Please make sure to cite the following paper if you use LHAPDF6:
 
  "LHAPDF6: parton density access in the LHC precision era"
  Eur.Phys.J. C75 (2015) 3, 132
  http://arxiv.org/abs/1412.7420
 
An earlier write-up of progress on LHAPDF6 appeared in the Les Houches workshop proceedings:
 
  "New access to PDF data via LHAPDF6", by A. Buckley
  in "Les Houches 2013: Physics at TeV Colliders: Standard Model Working Group Report"
  http://arxiv.org/abs/1405.1067
  http://inspirehep.net/search?p=find+eprint+1405.1067

Support and bug reporting

If you need assistance with LHAPDF, please contact the authors at lhapd.nosp@m.f-su.nosp@m.pport.nosp@m.@cer.nosp@m.n.ch . 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.

For developers

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:

Git repository: https://gitlab.com/hepcedar/lhapdf/
Bug reports & task tracking: https://gitlab.com/hepcedar/lhapdf/-/issues
Project to-do list
Todo List
Instructions for building and running migration scripts/programs
Coding style
Design

Todo
Add some developer build guides, including the autotools, Cython, etc. gotchas.

Table of Contents