Python tutorial

The pdfxtmd package exposes high-level set classes for uncertainty-aware analysis and factory classes for direct access to individual members.

Run the notebook online

Use the maintained Jupyter notebook to explore the Python interface in a hosted Google Colab runtime:

Open in Google Colab

Colab sessions are temporary. Run the notebook from the beginning in a fresh runtime. Packages and data downloaded during the session may need to be installed again after the runtime is reset.

Install the package locally

A virtual environment keeps the package isolated from other projects:

python -m venv .venv

Activate it, then install from PyPI:

python -m pip install --upgrade pip
python -m pip install pdfxtmd

The package still requires separately downloaded PDF or TMD data sets. Configure their parent directories using the PDF sets guide.

Collinear PDFs with CPDFSet 

import pdfxtmd

set_name = "CT18NLO"
cpdf_set = pdfxtmd.CPDFSet(set_name)

print(f"Loaded {set_name} with {len(cpdf_set)} members")

x = 0.01
mu2 = 100.0

central = cpdf_set[0]
up = central.pdf(pdfxtmd.PartonFlavor.u, x, mu2)
print(f"up-quark value = {up:.6g}")

Metadata, uncertainty, and correlation 

standard_info = cpdf_set.getStdPDFInfo()
error_info = cpdf_set.getPDFErrorInfo()

print("description:", standard_info.SetDesc)
print("members:", standard_info.NumMembers)
print("error type:", error_info.ErrorType)

uncertainty = cpdf_set.Uncertainty(
    pdfxtmd.PartonFlavor.u, x, mu2, cl=68.0
)
print(
    f"central={uncertainty.central:.6g}, "
    f"+{uncertainty.errplus:.6g}, "
    f"-{uncertainty.errminus:.6g}"
)

correlation = cpdf_set.Correlation(
    pdfxtmd.PartonFlavor.u, x, mu2,
    pdfxtmd.PartonFlavor.d, x, mu2,
)
print(f"correlation(u, d) = {correlation:.4f}")

TMDs with TMDSet 

import pdfxtmd

tmd_set = pdfxtmd.TMDSet("PB-LO-HERAI+II-2020-set2")

x = 0.001
kt2 = 10.0
mu2 = 100.0

central = tmd_set[0]
gluon = central.tmd(pdfxtmd.PartonFlavor.g, x, kt2, mu2)
print(f"gluon TMD value = {gluon:.6g}")

uncertainty = tmd_set.Uncertainty(
    pdfxtmd.PartonFlavor.g, x, kt2, mu2, cl=68.0
)
print(
    f"central={uncertainty.central:.6g}, "
    f"+{uncertainty.errplus:.6g}, "
    f"-{uncertainty.errminus:.6g}"
)

Single-member factories

Use factories when uncertainty analysis is unnecessary:

import pdfxtmd

cpdf_factory = pdfxtmd.GenericCPDFFactory()
cpdf = cpdf_factory.mkCPDF("CT18NLO", 0)

value = cpdf.pdf(pdfxtmd.PartonFlavor.g, 0.01, 100.0)
print("gluon value:", value)

tmd_factory = pdfxtmd.GenericTMDFactory()
tmd = tmd_factory.mkTMD("PB-LO-HERAI+II-2020-set2", 0)

tmd_value = tmd.tmd(pdfxtmd.PartonFlavor.g, 0.001, 10.0, 100.0)
print("gluon TMD value:", tmd_value)

Evaluate all flavors

The Python bindings can return all flavors in one call:

all_cpdf_flavors = cpdf.pdf(0.01, 100.0)
all_tmd_flavors = tmd.tmd(0.001, 10.0, 100.0)

print(all_cpdf_flavors)
print(all_tmd_flavors)

Use pdfxtmd.PartonFlavor.__members__ to inspect the available enum names and integer values rather than assuming an array order.

Strong coupling 

alpha_from_set = cpdf_set.alphasQ2(10000.0)
print("alpha_s from set:", alpha_from_set)

coupling_factory = pdfxtmd.CouplingFactory()
coupling = coupling_factory.mkCoupling("CT18NLO")
alpha_from_factory = coupling.AlphaQCDMu2(10000.0)
print("alpha_s from factory:", alpha_from_factory)

Handle invalid input

Bindings report invalid kinematics or missing sets as Python exceptions:

try:
    cpdf.pdf(pdfxtmd.PartonFlavor.u, -0.1, 100.0)
except RuntimeError as error:
    print("PDFxTMDLib error:", error)

Further reading