Skip to content

CLI Tutorials

The neopdf CLI tool provides a command-line interface to the NeoPDF library, enabling users to perform PDF interpolation, alpha_s evaluation, file format conversion, and metadata inspection directly from the terminal. Below are detailed usage instructions and examples for each major feature.

How to use the new NeoPDF format?

  • To use the NeoPDF grid format, if available, simply append .neopdf.lz4 to the name of the PDF set; LHAPDF sets can be converted into the NeoPDF format using the CLI (see below)
  • The CLI supports both eager and lazy loading of grids, and can operate on both standard and compressed formats
  • For more advanced usage, see the help output:
neopdf --help

Reading PDF Metadata and Grid Information

Read Metadata for a PDF Set

To read the metadata for a given PDF set:

neopdf read metadata --pdf-name NNPDF40_nnlo_as_01180
  • --pdf-name: Name of the PDF set (can be a NeoPDF or LHAPDF set).

The above command will print out the following output:

Set Description: NNPDF4.0 NNLO global fit, alphas(MZ)=0.1180. mem=0 => average on replicas; mem=1-100 => PDF replicas
Set Index: 331100
Number of Members: 101
XMin: 0.000000001
XMax: 1
QMin: 1.65
QMax: 100000
Flavors: [-5, -4, -3, -2, -1, 21, 1, 2, 3, 4, 5]
Format: lhagrid1
...
Polarized: false
Set Type: SpaceLike
Interpolator Type: LogBicubic
...

Get the Number of Subgrids

To get the number of subgrids a PDF contains:

neopdf read num_subgrids --pdf-name NNPDF40_nnlo_as_01180
  • --pdf-name: Name of the PDF set.

Get Knot Values for a Subgrid

To get the knot values for a given subgrid:

neopdf read subgrid_info --pdf-name NNPDF40_nnlo_as_01180 --member 0 --subgrid-index 1
  • --pdf-name: Name of the PDF set.
  • --member: The member index (0-based).
  • --subgrid-index: The index of the subgrid to inspect.

The above command will print out the following output:

Nucleon Numbers A: [1.0], shape=[1], strides=[1], layout=CFcf (0xf), const ndim=1
Alphas values: [0.118], shape=[1], strides=[1], layout=CFcf (0xf), const ndim=1
kT values: [0.0], shape=[1], strides=[1], layout=CFcf (0xf), const ndim=1
x values: [1e-9, 1.2970848e-9, ...], shape=[196], strides=[1], layout=CFcf (0xf), const ndim=1
Q2 values: [2.7224999999999997, ...], shape=[12], strides=[1], layout=CFcf (0xf), const ndim=1

Updating Grid Metadata

The metadata of a given NeoPDF grid can be updated by running the following command:

neopdf write metadata --path NNPDF40_nnlo_as_01180.neopdf.lz4 --key SetType --value TimeLike
  • --path: Path to the NeoPDF set.
  • --key: The key value of the metadata to be updated, see the rename field of the MetaData struct for the available keys.
  • --value: The updated value of the metadata.

Computing Interpolated Values

Compute interpolated PDF values \(xf(x, Q^2)\)

To compute the interpolated function \(xf(x, Q^2)\) for a given PDF set, member, and flavor:

neopdf compute xfx_q2 --pdf-name NNPDF40_nnlo_as_01180 --member 0 --pid 21 1e-3 10.0
  • --pdf-name: Name of the PDF set (can be a NeoPDF or LHAPDF set).
  • --member: The member index (0-based).
  • --pid: The PDG ID of the parton flavor (e.g., 21 for gluon).
  • If the PDF set doesn't have the \(\alpha_s\) and \(A\) dependence, then the last two arguments are simply the \(x\) and \(Q^2\) values at which to evaluate the PDF.

More about the last argument

In the case where the PDF set contains an \(\alpha_s\) and/or \(A\) dependence, the the argument should be either \((A, x, Q^2)\), \((\alpha_s, x, Q^2)\), \((k_T, x, Q^2)\), \((A, \alpha_s, x, Q^2)\), \((A, k_T, x, Q^2)\), \((\alpha_s, k_T, x, Q^2)\), or \((A, \alpha_s, k_T, x, Q^2)\) depending on what the grid contains. See the section below for an example where the grid contains an \(A\)-dependence.

Compute strong coupling \(\alpha_s\) at a given \(Q^2\)

To compute the strong coupling constant \(\alpha_s(Q^2)\) for a given PDF set and member:

neopdf compute alphas_q2 --pdf-name NNPDF40_nnlo_as_01180 --member 0 --q2 10
  • --q2: The \(Q^2\) value at which to evaluate \(\alpha_s\).

Converting LHAPDF Sets into NeoPDF Format

Convert standard LHAPDF to NeoPDF format

To convert a standard LHAPDF set into the new, compressed NeoPDF format:

neopdf write convert --pdf-name NNPDF40_nnlo_as_01180 --output NNPDF40_nnlo_as_01180.neopdf.lz4
  • --output: The output file name for the NeoPDF grid (should end with .neopdf.lz4).

Combine multiple LHAPDF Nuclear PDFs

To combine several LHAPDF nuclear PDF sets into a single NeoPDF grid:

neopdf write combine-npdfs --pdf-names nNNPDF30_nlo_as_0118_p nNNPDF30_nlo_as_0118_A12 nNNPDF30_nlo_as_0118_A40 --output nNNPDF30_nlo_as_0118.neopdf.lz4
  • --pdf-names: List of PDF set names to combine.
  • --output: Output file for the combined grid.

Alternatively, one can pass the names of the PDFs via an input file where each line contains a PDF name. Taking the example of nuclear PDFs above but using all the \(A\) sets available,

nuclearpdfs.txt
nNNPDF30_nlo_as_0118_p
nNNPDF30_nlo_as_0118_A2_Z1
nNNPDF30_nlo_as_0118_A4_Z2
nNNPDF30_nlo_as_0118_A6_Z3
nNNPDF30_nlo_as_0118_A9_Z4
nNNPDF30_nlo_as_0118_A12_Z6
nNNPDF30_nlo_as_0118_A14_Z7
nNNPDF30_nlo_as_0118_A16_Z8
nNNPDF30_nlo_as_0118_A27_Z13
nNNPDF30_nlo_as_0118_A31_Z15
nNNPDF30_nlo_as_0118_A40_Z20
nNNPDF30_nlo_as_0118_A56_Z26
nNNPDF30_nlo_as_0118_A64_Z29
nNNPDF30_nlo_as_0118_A108_Z54
nNNPDF30_nlo_as_0118_A119_Z59
nNNPDF30_nlo_as_0118_A131_Z54
nNNPDF30_nlo_as_0118_A184_Z74
nNNPDF30_nlo_as_0118_A197_Z79
nNNPDF30_nlo_as_0118_A208_Z82

the command now becomes:

neopdf write combine-npdfs --names-file nuclearpdfs.txt --output nNNPDF30_nlo_as_0118.neopdf.lz4

This will generate a nNNPDF30_nlo_as_0118.neopdf.lz4 PDF grid that also contains the \(A\) dependence. One can now check the value of \(xf(A, x, Q^2)\) for the Iron \(^{56}_{26}\mathrm{Fe}\):

neopdf compute xfx_q2 --pdf-name nNNPDF30_nlo_as_0118.neopdf.lz4 --member 0 --pid 21 56 1e-3 10.0

Combine multiple \(\alpha_s\) LHAPDF sets

To combine multiple \(\alpha_s\) LHAPDF sets into a single NeoPDF grid with an explicit dependence on \(\alpha_s\), the procedure is the same as when combining multiple nuclear PDFs with the option combine-npdfs replaced with combine-alphas. That is, given an input file with the names of the PDF sets:

alphaspdfs.txt
NNPDF40_nnlo_as_01160
NNPDF40_nnlo_as_01170
NNPDF40_nnlo_as_01175
NNPDF40_nnlo_as_01185
NNPDF40_nnlo_as_01190

The command to run is:

neopdf write combine-alphas --names-file alphaspdfs.txt --output NNPDF40_nnlo.neopdf.lz4

Note that the names of the PDF sets can be passed via the command line using the option --pdf--name. We can then interpolate the \(\alpha_s = 0.1180\) value:

neopdf compute xfx_q2 --pdf-name NNPDF40_nnlo.neopdf.lz4 --member 0 --pid 21 0.1180 1e-3 10.0

Warning

Given that LHAPDF doesn't provide specific attributes to extract the values of \(A\) and \(\alpha_s\), their values are inferred from the set name. The extraction of these values are therefore set dependent and we try to support as many sets as possible while keeping the implementation modular. The current extraction of these values rely on the following regex:

// Regexes to extract A from the PDF set name
let re_nnpdf = Regex::new(r"_A(\d+)").unwrap();
let re_ncteq = Regex::new(r"_(\d+)_(\d+)$").unwrap();
let re_epps = Regex::new(r"[a-zA-Z]+(\d+)$").unwrap();

// Regexes to extract alpha_s from the PDF set name
let re_nnpdf_ct = Regex::new(r"_as_(\d+)_?").unwrap();
let re_msht = Regex::new(r"_as(\d+)").unwrap();

This approach is not fullproof and some PDF sets might not be supported at all.