PDFxTMDLib is a high-performance C++ library for parton distribution functions (PDFs), supporting both collinear PDFs (cPDFs) and transverse momentum-dependent PDFs (TMDs). It is designed with modern C++17 principles for performance and extensibility, and provides interfaces for reading standard PDF grid files (LHAPDF, TMDLib) as well as custom formats.
For a comprehensive understanding of the library's architecture, features, and performance benchmarks, please refer to the full paper available on arXiv: https://arxiv.org/abs/2412.16680.
- Extensibility: Easily create custom PDF implementations through template specialization.
- Cross-platform: Full support for Linux, Windows, and macOS.
- Modern C++: Built with C++17 for maximum performance and reliability.
- Wrappers: Fortran and Python wrappers for easy integration.
Before installing PDFxTMDLib, ensure your system meets these requirements:
- C++17 compatible compiler: GCC 8+, Clang 7+, MSVC 2019+
- CMake: Version 3.14 or newer
- For Windows: Microsoft Visual Studio 2019 or newer
The library uses a standard CMake build process. Execute the following commands in your terminal:
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -S ..
cmake --build .To install the library system-wide (recommended for Linux/macOS), execute the following command from the build directory. This may require administrative privileges.
cmake --install .This installs headers, libraries, and CMake configuration files to standard system locations.
PDFxTMDLib offers a flexible API with both high-level conveniences and low-level control.
For projects using CMake, add these lines to your CMakeLists.txt file to link against the installed library:
find_package(PDFxTMDLib REQUIRED)
target_link_libraries(your-target-name PDFxTMD::PDFxTMDLib)You can also link directly with the compiler.
Linux/macOS (GCC/Clang):
g++ -std=c++17 your_source.cpp -lPDFxTMDLib -o your_executableWindows (MSVC from Developer Command Prompt):
cl your_source.cpp /std:c++17 PDFxTMDLib.libThe PDFSet template class is the interface for most applications. It abstracts away the complexities of managing PDF set members and provides a unified API for calculations, uncertainty analysis, and metadata access.
This example shows how to instantiate a collinear PDF set and evaluate the gluon PDF.
#include <PDFxTMDLib/PDFSet.h>
#include <iostream>
int main() {
// Instantiate a PDFSet for a collinear distribution set
PDFxTMD::PDFSet<PDFxTMD::CollinearPDFTag> cpdfSet("MSHT20nlo_as120");
// Access the central member (index 0)
auto central_pdf = cpdfSet[0];
// Define kinematics
double x = 0.1;
double mu2 = 10000; // Factorization scale squared
// Evaluate the gluon PDF
double gluon_pdf = central_pdf->pdf(PDFxTMD::PartonFlavor::g, x, mu2);
std::cout << "Gluon PDF at x=" << x << ", mu2=" << mu2 << " GeV2: " << gluon_pdf << std::endl;
return 0;
}The process for TMDs is similar, specializing the PDFSet with TMDPDFTag and including the transverse momentum parameter
#include <PDFxTMDLib/PDFSet.h>
#include <iostream>
int main() {
// Instantiate a PDFSet for a TMD distribution set
PDFxTMD::PDFSet<PDFxTMD::TMDPDFTag> tmdSet("PB-LO-HERAI+II-2020-set2");
// Access the central member (index 0)
auto central_tmd = tmdSet[0];
// Define kinematics
double x = 0.001;
double kt2 = 10;
double mu2 = 100;
// Evaluate the up-quark TMD
double up_tmd = central_tmd->tmd(PDFxTMD::PartonFlavor::u, x, kt2, mu2);
std::cout << "Up-quark TMD at x=" << x << ", kt2=" << kt2 << ", mu2=" << mu2 << ": " << up_tmd << std::endl;
return 0;
}PDFxTMDLib automates uncertainty and correlation calculations based on the PDF set's metadata (Hessian or Monte Carlo).
#include <PDFxTMDLib/PDFSet.h>
#include <iostream>
int main() {
PDFxTMD::PDFSet<PDFxTMD::CollinearPDFTag> cpdfSet("MSHT20nlo_as120");
double x = 0.1;
double mu2 = 10000;
// Calculate PDF uncertainty at the default confidence level
PDFxTMD::PDFUncertainty uncertainty = cpdfSet.Uncertainty(PDFxTMD::PartonFlavor::g, x, mu2);
std::cout << "xg = " << uncertainty.central << " + " << uncertainty.errplus << " - " << uncertainty.errminus << std::endl;
// Calculate uncertainty at 90% confidence level
PDFxTMD::PDFUncertainty uncertainty_90 = cpdfSet.Uncertainty(PDFxTMD::PartonFlavor::g, x, mu2, 90.0);
std::cout << "xg (90% CL) = " << uncertainty_90.central << " + " << uncertainty_90.errplus << " - " << uncertainty_90.errminus << std::endl;
// Calculate correlation between gluon and up quark
double correlation = cpdfSet.Correlation(PDFxTMD::PartonFlavor::g, x, mu2, PDFxTMD::PartonFlavor::u, x, mu2);
std::cout << "Correlation between g and u: " << correlation << std::endl;
return 0;
}For applications that only need a specific PDF member without uncertainty analysis, factories provide a more direct and efficient approach.
#include <PDFxTMDLib/GenericCPDFFactory.h>
#include <PDFxTMDLib/GenericTMDFactory.h>
#include <iostream>
int main() {
using namespace PDFxTMD;
double x = 0.001, mu2 = 100, kt2 = 10;
// Create a single cPDF member using a factory
auto cpdf_factory = GenericCPDFFactory();
auto cpdf = cpdf_factory.mkCPDF("MMHT2014lo68cl", 0);
double gluon_cpdf = cpdf.pdf(PartonFlavor::g, x, mu2);
std::cout << "Gluon cPDF: " << gluon_cpdf << std::endl;
// Create a single TMD member using a factory
auto tmd_factory = GenericTMDFactory();
auto tmd = tmd_factory.mkTMD("PB-LO-HERAI+II-2020-set2", 0);
double gluon_tmd = tmd.tmd(PartonFlavor::g, x, kt2, mu2);
std::cout << "Gluon TMD: " << gluon_tmd << std::endl;
return 0;
}The strong coupling constant PDFSet instance or using a CouplingFactory.
#include <PDFxTMDLib/PDFSet.h>
#include <PDFxTMDLib/CouplingFactory.h>
#include <iostream>
int main() {
using namespace PDFxTMD;
double mu2 = 10000;
// Method 1: Using PDFSet
PDFSet<CollinearPDFTag> cpdfSet("MSHT20nlo_as120");
double alpha_s_from_set = cpdfSet.alphasQ2(mu2);
std::cout << "alpha_s from PDFSet: " << alpha_s_from_set << std::endl;
// Method 2: Using CouplingFactory
auto couplingFactory = CouplingFactory();
auto coupling = couplingFactory.mkCoupling("MMHT2014lo68cl");
double alpha_s_from_factory = coupling.AlphaQCDMu2(mu2);
std::cout << "alpha_s from Factory: " << alpha_s_from_factory << std::endl;
return 0;
}PDFxTMDLib allows advanced users to construct PDF objects with custom components (e.g., reader, interpolator, extrapolator) by specializing the GenericPDF template. Type aliases are also available for convenience.
#include <PDFxTMDLib/GenericPDF.h>
#include <PDFxTMDLib/Implementation/Extrapolator/Collinear/CErrExtrapolator.h>
#include <PDFxTMDLib/Implementation/Interpolator/Collinear/CLHAPDFBilinearInterpolator.h>
#include <PDFxTMDLib/Implementation/Reader/Collinear/CDefaultLHAPDFFileReader.h>
#include <iostream>
int main() {
using namespace PDFxTMD;
// Custom PDF implementation with specific components
using ReaderType = CDefaultLHAPDFFileReader;
using InterpolatorType = CLHAPDFBilinearInterpolator<ReaderType>;
using ExtrapolatorType = CErrExtrapolator;
GenericPDF<CollinearPDFTag, ReaderType, InterpolatorType, ExtrapolatorType>
custom_cpdf("MMHT2014lo68cl", 0);
// Using convenient type aliases (equivalent to default implementations)
CollinearPDF cpdf("MMHT2014lo68cl", 0);
TMDPDF tmd("PB-LO-HERAI+II-2020-set2", 0);
return 0;
}PDFxTMDLib provides a native Python interface using pybind11, exposing all major features of the C++ library.
Install the wrapper directly from PyPI:
pip install pdfxtmdimport pdfxtmd
# Create a collinear PDF object using the factory
cpdf_factory = pdfxtmd.GenericCPDFFactory()
cpdf = cpdf_factory.mkCPDF("CT18NLO", 0)
x = 0.01
mu2 = 100
up_pdf = cpdf.pdf(pdfxtmd.PartonFlavor.u, x, mu2)
print(f"Up quark PDF: {up_pdf}")
# Create a TMD PDF object using the factory
tmd_factory = pdfxtmd.GenericTMDFactory()
tmd = tmd_factory.mkTMD("PB-NLO-HERAI+II-2023-set2-qs=0.74", 0)
kt2 = 10
gluon_tmd = tmd.tmd(pdfxtmd.PartonFlavor.g, x, kt2, mu2)
print(f"Gluon TMD: {gluon_tmd}")
# Compute all flavors at once
all_flavors = []
cpdf.pdf(x, mu2, all_flavors)
print(f"All flavors: {all_flavors}")import pdfxtmd
coupling_factory = pdfxtmd.CouplingFactory()
coupling = coupling_factory.mkCoupling("CT18NLO")
for scale in [10, 100, 1000, 10000]:
print(f"Alpha_s at mu2={scale}: {coupling.AlphaQCDMu2(scale)}")Full Python documentation: > See
examples/python/readme-pyversion.mdfor a complete guide and advanced usage.
- Jupyter Notebook Tutorial (run online): Open in Google Colab
- Local Example: See
examples/python/python_tutorial.py
PDFxTMDLib uses a config.yaml file to locate PDF data sets. The library searches for this file in the following locations:
- Windows:
C:\ProgramData\PDFxTMDLib\config.yaml - Linux/macOS:
~/.PDFxTMDLib/config.yaml
Example config.yaml:
paths:
- /path/to/my/pdf/sets
- /another/path/to/pdf/dataThe paths key accepts a list of directories where PDFxTMDLib will search for PDF set data. The current directory and standard system locations are searched by default. In order to download cPDF sets use lhapdf sets available at link, and to download TMD sets visit the official website of this repository available at pdfxtmdlib.org.
For easy visualization of PDFs and TMDs, you can use the QtPDFxTMDPlotter, a Qt-based graphical tool built on top of PDFxTMDLib.
Contributions are welcome! If you are interested in contributing to the project, please open an issue or contact raminkord92@gmail.com.
This project is licensed under the GPL-3.0 License. For more details, see the LICENSE file.
For any inquiries, please contact raminkord92@gmail.com.