PineAPPL: Fast Grid Library for Hadronic Predictions
- PineAPPL is a lightweight, stand-alone library that generates PDF-independent interpolation grids for fast evaluation of high-energy observables.
- It decouples expensive fixed-order Monte Carlo integration from subsequent convolutions with parton distribution and fragmentation functions, enabling rapid scale and uncertainty studies.
- Its flexible architecture supports arbitrary convolutions with higher-order QCD and electroweak corrections and interfaces seamlessly with external generators and evolution tools.
PineAPPL is a lightweight, stand-alone library whose main goal is to decouple the expensive fixed-order Monte Carlo integration of hadronic cross sections from the subsequent convolution with parton distribution functions, while at the same time supporting not only higher-order QCD effects but also electroweak corrections and their mixed QCD–EW contributions. It produces PDF-independent interpolation grids of partonic cross sections that can be convolved a posteriori with PDFs and, in PineAPPL v1, also with fragmentation functions for the fast evaluation of high-energy physical observables. The library has been used in precision phenomenology, in PDF determinations, and in interfaces to general-purpose Monte Carlo generators and analytic DIS codes; its later development extends the framework to an arbitrary number of convolutions, including unpolarised and polarised distributions with space-like or time-like evolution (Carrazza et al., 2020, Ježo et al., 15 Jun 2026).
1. Purpose, scope, and role in theory-prediction workflows
PineAPPL implements a two-step strategy. In the grid-generation step, a Monte Carlo integration or an analytic calculation records partonic weights in a PDF- and scale-independent format. In the fast-convolution step, the resulting grids are convolved with any PDF set, and scale or variations are carried out a posteriori in seconds rather than by rerunning the full partonic calculation. This design is central to FastKernel-style workflows, where PineAPPL acts as the “grid engine” that tabulates short-distance coefficients onto an interpolation grid in partonic kinematic variables, and later reduces the hadronic prediction to linear algebra operations (Barontini et al., 2023).
Within the “Pineline” framework, PineAPPL is paired with auxiliary tools that serve distinct roles in theory prediction. PineAPPL provides the grid operations; pinefarm interfaces external generators or analytic DIS codes to produce .pineappl grids; eko produces evolution-kernel operators for DGLAP evolution; pineko combines a PineAPPL grid with an evolution operator to build the final FK table; and yadism provides a DIS library that can generate interpolation grids in the PDF-independent PineAPPL format (Barontini et al., 2023, Candido et al., 2024).
The early collider-focused presentations emphasize features that distinguish PineAPPL from earlier grid software: support for arbitrary powers of the strong and electroweak couplings, mixed QCD–EW terms, photon- and lepton-initiated channels, on-the-fly renormalisation and factorisation scale variations, and a thread-safe C++ interface. Later work broadens the same logic beyond hadron-collider PDF convolutions to multiple convolutions involving PDFs and FFs, with control of renormalisation, initial-state factorisation, and final-state fragmentation scales (Carrazza et al., 2020, Carrazza et al., 2020, Ježo et al., 15 Jun 2026).
2. Mathematical formulation and interpolation strategy
The hadronic cross section underlying PineAPPL is written as a factorised convolution of PDFs with perturbative coefficient functions. In one formulation,
PineAPPL stores the coefficient functions on a discrete grid of nodes and reconstructs the observable by interpolation, so that the expensive integrals are performed once while later evaluations amount to sums over precomputed weights times PDF values and coupling factors (Schwan, 2021).
The interpolation itself is based on Lagrange or piecewise-polynomial bases. A generic representation used in the literature is
with compactly supported basis functions and coefficients accumulated event by event during Monte Carlo integration. In the original LHC-process implementation, PineAPPL used a 3D Lagrange-interpolation grid in transformed variables
with nodes and interpolation order ; each event updated only the neighboring nodes surrounding the mapped point (Carrazza et al., 2020).
Process-specific interfaces often instantiate lower-dimensional grids tailored to the measurement. In the NNLO top-pair implementation inside a customized MATRIX code, 2D interpolation grids were built in and with a tensor-product polynomial basis of order ,
0
where the weights 1 are accumulated during the run and stored in the PineAPPL file (Garzelli et al., 2023).
PineAPPL v1 generalises this picture to an arbitrary number of convolution variables. Each weight coefficient lives on an 2-dimensional hypercube, is internally linearised in row-major order, and is stored sparsely via a custom PackedArray that groups consecutive non-zero entries into blocks. The stated motivation is that memory usage should scale with the actual populated fraction of the grid rather than the full hypervolume, which is especially relevant when a process involves several PDFs, FFs, polarisation states, or independent scales (Ježo et al., 15 Jun 2026).
3. Software architecture and interfaces
The software architecture described across the literature revolves around a top-level grid object together with process-specific wrappers that translate generator event records into grid fills. In the NNLOJET interface for Drell–Yan, the architecture is described in terms of a Grid, a Profiler, and a Wrapper: the Grid stores the coefficients on a Cartesian mesh of nodes in 3 and by perturbative order, the Profiler accepts one event at a time and distributes its weights onto nearby nodes by evaluating Lagrange basis functions, and the Wrapper is the glue layer that lives inside an external Monte Carlo generator and handles booking, filling, and finalisation (Cruz-Martinez et al., 22 Jan 2025).
The library is exposed through C/C++, Python, Fortran, and Rust interfaces, and command-line tools are available for reading, convolving, plotting, or evolving grids. The file formats discussed in the literature include .pine, .pineappl, .pineappl.lz4, and .lz4, with stored metadata such as bin boundaries, interpolation degree, perturbative order, scale-variation settings, and partonic-channel information (Candido et al., 2024, Devoto et al., 17 Jun 2025).
A defining architectural feature is the ease of integration into external codes. MadGraph5_aMC@NLO was interfaced to PineAPPL through a custom plugin replacing aMCfast, thereby enabling NLO QCD+EW grids for LHC processes. MATRIX was later interfaced to PineAPPL through the “Matrix Hawaii” implementation, activated by the --hawaii flag and preserving MATRIX features such as simultaneous computation at several slicing parameters 4 and numerical 5 extrapolation. yadism creates and fills PineAPPL grids for DIS observables directly from Python, while VegasFlow demonstrates synchronous and asynchronous filling strategies for accelerator-driven event generation (Schwan, 2021, Devoto et al., 17 Jun 2025, Candido et al., 2024, Carrazza et al., 2020).
The same interface pattern is visible in specific implementations. In the MATRIX top-pair setup, the analysis module defined a GridConfig, created a grid with pineappl::createGrid(cfg), filled it at each phase-space point through grid->fill({Mtt,aytt}, w0, x1, x2, scIndex), finalised it, and later reloaded it for convolutions with different PDF sets and scale choices. The API was extended there so that the scale-variation index scIndex could cover up to 7-point 6 runs in one pass, and so that the grid header carried explicit metadata on the order of 7 and the perturbative order (Garzelli et al., 2023).
4. PDF independence, uncertainty propagation, and PDF fitting
A central property of PineAPPL grids is that they are by construction PDF-independent. Once the tabulated weights are known, the hadronic cross section for any candidate PDF can be assembled by a simple linear algebra operation. In matrix notation, if 8 is the stacked vector of PDF values on the interpolation nodes and 9 is the row vector of weights for experimental bin 0, then
1
and a full dataset is obtained as 2. This reduction is the reason PineAPPL is used inside PDF fits, where repeated reevaluation for many PDF replicas would otherwise require repeated partonic integrations (Barontini et al., 2023).
The library also stores explicit perturbative-order information and scale dependence. In the top-pair MATRIX implementation, a single run produced event weights for the central scale and six variations, and PineAPPL stored seven separate weight sets,
3
When reading the grid, PDF and 4 variations were evaluated by repeated calls to grid.convolute(pdf[iPDF], \alpha_s_pdf[iPDF], \mu_R[k], \mu_F[k]), with on-the-fly reweighting implemented as
5
Combined scale, PDF, and 6 studies then reduce to loops over PDF members and scale indices, followed by an envelope or correlation matrix construction (Garzelli et al., 2023).
This exact dependence on PDFs and perturbative channels is one reason PineAPPL has been used to scrutinize the widespread 7-factor approximation. The NNLOJET Drell–Yan study reports stability of NNLO 8-factors under PDF variation to 9 and finds that, in a full PDF fit using exact grids versus an NLO+0-factor approximation, shifts in PDFs are 1 and well within uncertainties. By contrast, the MATRIX Hawaii study states that while overall 2 profiles differed by only a few percent near the initial PDF, larger discrepancies, up to several-percent shifts in 3, appeared farther from that point, showing that naïve 4-factors can introduce a non-negligible bias. The combined picture suggests that the adequacy of a 5-factor approximation is process- and fit-dependent, and that exact grids remove the approximation altogether (Cruz-Martinez et al., 22 Jan 2025, Devoto et al., 17 Jun 2025).
5. Process coverage, benchmarks, and validation
PineAPPL has been applied to DIS, Drell–Yan, top–antitop production, heavy-flavor production, and hardware-accelerated Monte Carlo workflows. In yadism, the library supports computations of polarized and unpolarized DIS structure functions and cross sections up to N6LO in perturbative QCD, with FFNS, FFN0, and ZM-VFNS options, and with tools for the generation of interpolation grids in PDF-independent PineAPPL format. The benchmark summary reports discrepancies below 7 for unpolarized massless 8 and 9 in ZM-VFNS versus QCDNUM/APFEL++, agreement within 0 for polarized 1 at NLO/N2LO versus APFEL++, and charm-tagged 3 agreement at NLO to 4 and at NNLO to 5 versus APFEL++. A 6 grid with 10 bins and NNLO coefficients takes 7–8 to build on a single modern core, and evaluating any PDF on the grid is then 9 (Candido et al., 2024).
For Drell–Yan with NLO electroweak corrections, PineAPPL was interfaced to MadGraph5_aMC@NLO and used to examine observables where EW effects are sizeable. Around the 0 peak, the NLO EW/QED corrections in the invariant-mass distribution reach 1 and reshape the line shape; at high 2, weak Sudakov logarithms drive corrections to 3 or more. In the same implementation, grid generation typically costs 4–5 for NLO QCD+EW Drell–Yan on a single modern CPU core, a fully differential grid with scale-variation tables occupies 6–7 on disk, and convolution takes a few seconds (Schwan, 2021).
The NNLOJET interface addresses the longstanding absence of NNLO Drell–Yan interpolation grids. For a single Drell–Yan measurement with 30 bins, 4 axes, 3 orders, and 8 events, grid construction is reported as approximately 2 hours wall time on 400 cores, the final grid file size is 9, and reading plus evaluating one PDF with a 9-point scale scan and PDF uncertainties takes less than 5 seconds on a single core. Closure tests show 0 and 1 even in forward regions, while the direct Monte Carlo error is 2 (Cruz-Martinez et al., 22 Jan 2025).
In NNLO top–antitop production, PineAPPL was embedded into a customized MATRIX code and validated by comparison of direct histogramming in MATRIX versus PineAPPL-reweighted results in 50 test bins. The quoted maximum deviation per bin is 3 and the average is approximately 4. The grid-generation cost is substantial—5 NNLO events and CPU time 6 core·hours, parallelized over 500 cores for two weeks—but subsequent reevaluation is very fast: a PDF loop over 100 members, 7 scales, and 50 bins takes 7 on a single core (Garzelli et al., 2023).
Open heavy-flavor production in the GM-VFNS provides another benchmark. There the stated achievement is better than permille agreement between the grids and the Monte Carlo predictions, without substantially increasing the time of the Monte Carlo calculations. In a typical GM-VFNS run, the overhead of grid creation was 8 of the total MC time, writing the grid to disk took 9, and a PDF-uncertainty evaluation with 347 PDF members yielded a net speed-up of 0 for that step alone (Wissmann et al., 2024).
Hardware-accelerated workflows have also been studied. In the VegasFlow setting, synchronous filling increases runtime relative to no-grid integration by 1 on CPU and 2 on GPU for the benchmark process, while an asynchronous approach reduces the extra overhead by approximately 10 percentage points in both cases, to 3 on CPU and 4 on GPU. The same study argues that for realistic NLO or NNLO processes, where matrix elements are more expensive, the relative penalty of grid filling is smaller (Carrazza et al., 2020).
6. Extensions, practical guidance, and nomenclature
PineAPPL v1 extends the grid formalism from the standard two-PDF case to an arbitrary number of nonperturbative factors. It supports PDFs, polarized PDFs, and FFs; unpolarised and polarised distributions; space-like and time-like evolution; and independent control of renormalisation, initial-state factorisation, and final-state fragmentation scales. It can store two kinematic scales per event and allows each of 5, 6, and 7 to be set to analytic combinations such as quadratic sum, quadratic mean, linear sum, linear mean, maximum, minimum, product, or weighted average. Standard 7-point, 15-point, 17-point, and 27-point scale-variation prescriptions are described, and the convolution over PDF or FF replicas is stated to take typically a few milliseconds per replica (Ježo et al., 15 Jun 2026).
Several usage guidelines recur across the literature. For new processes, the recommended procedure is to define the grid variables, bin edges, and interpolation order inside the process-specific analysis routine; create and fill the grid exactly at the point where the Monte Carlo weight is known; finalise the grid and write the .pine or .pineappl file; and validate a small subset of bins by direct histogramming. Additional recommendations include matching the grid binning exactly to the experimental measurement to avoid extrapolation, assigning an additional per-bin interpolation uncertainty—8 uncorrelated in one NNLO top-pair implementation—when pushing to sub-per-mille precision, archiving both the code version and the exact grid files used for PDF/9/scale studies, uploading grids to HepData or a public Git repository, and providing a YAML or JSON manifest with kinematic variables, bin edges, perturbative order, PDF compatibility, and scale-variation indices (Garzelli et al., 2023).
For accelerator-oriented workflows, the practical recommendations are to use large batch sizes of approximately 0–1, allocate host buffers as pinned memory, size the CPU thread pool to the number of physical cores minus one, enable internal OpenMP parallelism when the grid has many channels, and on multi-GPU systems assign each GPU a separate integrator and thread-safe grid instance before aggregating the grids by coefficient summation (Carrazza et al., 2020).
A common source of confusion is nomenclature. Separate work on probabilistic programming introduces a language called pineappl, described as an imperative language that performs exact probabilistic inference with support for nested marginal maximum a posteriori optimization via staging. That usage refers to a weighted-BDD and branch-and-bound semiring framework for exact inference and MMAP, rather than to the high-energy-physics interpolation-grid library. The shared name does not imply a shared technical domain; in collider phenomenology, PineAPPL denotes the grid library for fast theory predictions (Cho et al., 26 Feb 2025).
Future directions stated in the literature include N2LO perturbative support once partonic weights are available, GPU-accelerated profiler fill routines, direct multi-threaded evaluation of basis functions and sparse-array decoding, on-the-fly dynamic rebinning, export to other fast-interpolation formats, and wider public release of process grids for current and future collider analyses (Cruz-Martinez et al., 22 Jan 2025, Devoto et al., 17 Jun 2025, Ježo et al., 15 Jun 2026).