PineAPPL’s Python API

PyO3 Python module that contains all exposed classes from Rust.

Bins, orders, channels (boc)

Interface for bins, orders and channels.

class pineappl.boc.Bin(bin_limits, normalization)

Bases: object

PyO3 wrapper to pineappl::boc::Bin.

bin_limits

Get the edges of this given bin.

Returns:: edges of the current bin
Return type:: list(tuple(float, float))

dimensions

Get the dimension for a given bin.

Returns:: dimension on which the observable is defined
Return type:: int

normalization

Get the normalization factor for this given bin.

Returns:: normalization factor
Return type:: float

class pineappl.boc.BinsWithFillLimits(bins, fill_limits)

Bases: object

PyO3 wrapper to pineappl::boc::Bin.

bin_limits()

Get the bin limits/edges.

Returns:: the bin edges with shape (n_bins, n_dimension, 2)
Return type:: list(list(tuple(float, float)))

bin_normalizations()

Get the normalizations of all bins.

Returns:: a list containing the normalizations
Return type:: list(float)

bins()

Get the list of Bin specifications.

Returns:: a list of Bin objects
Return type:: list(Bin)

dimensions()

Get the dimensions of the bins.

Returns:: dimension of the defined observable
Return type:: int

static from_fill_limits(fill_limits)

Construct the bin specifications using the bin edges.

# Panics

Panics if fill_limits cannot be converted into valid bins.

Parameters:: fill_limits (list(float)) – edges of the bins

static from_limits_and_normalizations(limits, normalizations)

Construct the bin specifications using the edges and the normalizations.

# Panics

Panics if limits and normalizations are inconsistent with the Rust constructors.

Parameters:

limits (list(list(float, float))) – edges of the bins
normalizations (list(float)) – a list of normalization factors

len()

Get the size/length of the bins.

Returns:: the size of the bins
Return type:: int

removed_index(index)

Get the removed bin using the index.

Parameters:: index (int) – index of the bin to be removed
Returns:: a Bin object from the removed index
Return type:: Bin

slices()

Get the bin slices.

Returns:: a list of indices representing the slices
Return type:: list(list(int))

class pineappl.boc.Channel(entry)

Bases: object

PyO3 wrapper to pineappl::boc::Channel.

Each entry consists of a tuple, which contains, in the following order:

a list containing the PDG value of the 1st, 2nd, and etc. of the incoming parton
a numerical factor that will multiply the result for this specific combination.

into_array()

Get list representation.

Returns:: list representation
Return type:: list(tuple(list(int),float))

class pineappl.boc.Kinematics

Bases: object

PyO3 wrapper to pineappl::boc::Kinematics.

class Scale(_0): Bases: Kinematics

class X(_0): Bases: Kinematics

class pineappl.boc.Order(alphas, alpha, logxir, logxif, logxia)

Bases: object

PyO3 wrapper to pineappl::boc::Order.

as_tuple()

Tuple representation.

Returns:

alphas (int) – power of alpha_s
alpha (int) – power of alpha (electroweak coupling)
logxir (int) – power of ln(xi_r)
logxif (int) – power of ln(xi_f)
logxia (int) – power of ln(xi_a)

static create_mask(orders, max_as, max_al, logs)

Return a mask suitable to pass as the order_mask parameter of [Grid::convolve].

The selection of orders is controlled using the max_as and max_al parameters, for instance setting max_as = 1 and max_al = 0 selects the LO QCD only, max_as = 2 and max_al = 0 the NLO QCD; setting max_as = 3 and max_al = 2 would select all NLOs, and the NNLO QCD.

See pineappl crate docs for more examples.

Returns:: boolean array, to be used as orders’ mask
Return type:: numpy.ndarray(bool)

class pineappl.boc.ScaleFuncForm

Bases: object

PyO3 wrapper to pineappl::boc::ScaleFuncForm.

class ExpProd2(_0, _1): Bases: ScaleFuncForm

class LinearMean(_0, _1): Bases: ScaleFuncForm

class LinearSum(_0, _1): Bases: ScaleFuncForm

class NoScale(_0): Bases: ScaleFuncForm

class Pow4Sum(_0, _1): Bases: ScaleFuncForm

class Prod(_0, _1): Bases: ScaleFuncForm

class QuadraticMean(_0, _1): Bases: ScaleFuncForm

class QuadraticSum(_0, _1): Bases: ScaleFuncForm

class QuadraticSumOver4(_0, _1): Bases: ScaleFuncForm

class S2plusS1fourth(_0, _1): Bases: ScaleFuncForm

class S2plusS1half(_0, _1): Bases: ScaleFuncForm

class Scale(_0): Bases: ScaleFuncForm

class ScaleMax(_0, _1): Bases: ScaleFuncForm

class ScaleMin(_0, _1): Bases: ScaleFuncForm

class WgtAvg(_0, _1): Bases: ScaleFuncForm

class pineappl.boc.Scales(ren, fac, frg)

Bases: object

PyO3 wrapper to pineappl::boc::Scales.

Convolutions

Define the type of convolutions.

class pineappl.convolutions.Conv(convolution_types, pid)

Bases: object

PyO3 wrapper to pineappl::convolutions::Conv.

convolution_types: Return the convolution type of this convolution.

pid: Return the PID of this convolution.

class pineappl.convolutions.ConvType(polarized, time_like)

Bases: object

PyO3 wrapper to pineappl::convolutions::ConvType.

polarized: Returns a boolean on whether or not the convolution type is polarized

time_like: Returns a boolean on whether or not the convolution type is timelike

Evolution

Evolution interface.

class pineappl.evolution.EvolveInfo(fac1, frg1, pids1, x1, ren1)

Bases: object

PyO3 wrapper to pineappl::evolution::EvolveInfo.

fac1

Squared factorization scales of the Grid.

Note: for pure time-like (FF) grids, PineAPPL stores only fragmentation scales. In that case, this getter returns frg1 as a backwards-compatible fallback.

frg1: Squared fragmentation scales of the Grid.

pids1: Particle identifiers of the Grid.

ren1: Renormalization scales of the Grid.

x1: x-grid coordinates of the Grid.

class pineappl.evolution.OperatorSliceInfo(fac0, pids0, x0, fac1, pids1, x1, pid_basis, convolution_types)

Bases: object

PyO3 wrapper to pineappl::evolution::OperatorSliceInfo.

FK tables

FK table interface.

class pineappl.fk_table.FkAssumptions(assumption)

Bases: object

PyO3 wrapper to pineappl::fk_table::FkAssumptions.

class pineappl.fk_table.FkTable(grid)

Bases: object

PyO3 wrapper to pineappl::fk_table::FkTable.

bin_dimensions()

Extract the number of dimensions for bins.

E.g.: two differential cross-sections will return 2.

Returns:: bin dimension
Return type:: int

bin_limits()

Get the limits/edges of all the bins.

Returns:: limits/edges of the bins with shape (n_bins, n_dimension, 2)
Return type:: list(list(float))

bin_normalizations()

Extract the normalizations for each bin.

Returns:: bin normalizations
Return type:: numpy.ndarray

bins()

Get number of bins.

Returns:: number of bins
Return type:: int

channels()

Get channels.

Returns:: channel functions as pid tuples
Return type:: list(tuple(float,float))

convolutions

Get the type(s) of convolution(s) for the current FK table.

Returns:: One entry per convolution (type and PID).
Return type:: list of PyConv

convolve(pdg_convs, xfxs, bin_indices=None, channel_mask=None)

Convolve the FK table with as many distributions.

xfx callables must return x * f (LHAPDF). If the underlying filling grid used pineappl.subgrid.ImportSubgridV1 (external coefficient dumps meant to fold with f), those values must have been stored as f, not x * f.

# Panics

Panics if Python PDF callbacks fail or if the underlying Rust convolution panics.

Parameters:

pdg_convs (list(PyConv)) – list containing the types of convolutions and PID
xfxs (list(callable)) – list of LHAPDF-like callables (pid, x, Q2) -> x * f
bin_indices (numpy.ndarray(int)) – A list with the indices of the corresponding bins that should be calculated. An empty list means that all bins should be calculated.
channel_mask (numpy.ndarray(bool)) – Mask for selecting specific channels. The value True means the corresponding channel is included. An empty list corresponds to all channels being enabled.

Returns:

cross sections for all bins

Return type:

numpy.ndarray(float)

fac0()

Get squared factorization scale.

Returns:: squared factorization scale
Return type:: float

frg0()

Get squared fragmentation scale.

Returns:: squared fragmentation scale
Return type:: float

metadata

Get metadata values stored in the grid.

Returns:: key, value map
Return type:: dict

optimize(assumptions)

Optimize storage.

In order to perform any relevant optimization, assumptions are needed, and they are passed as parameters to the function.

Parameters:: assumptions (PyFkAssumptions) – assumptions about the FkTable properties, declared by the user, deciding which optimizations are possible

pid_basis: Return the convention by which the channels’ PIDS are encoded.

static read(path)

Read an FK Table from given path.

# Panics

Panics if the file cannot be opened, the grid cannot be read, or it cannot be converted to an FK table.

Parameters:: path (str) – path to the FK table

rotate_pid_basis(pid_basis)

Rotate the F Table into the specified basis.

Parameters:: pid_basis (PyPidBasis) – PID basis of the resulting FK Table

set_metadata(key, value)

Set a metadata key-value pair in the FK Table.

Parameters:

key (str) – key
value (str) – value

table()

Get cross section tensor.

Returns:: 4-dimensional tensor with indixes: bin, channel, x1, x2
Return type:: numpy.ndarray

write(path)

Write to file.

# Panics

Panics if the specified path is non-writeable (non-existent or missing permissions).

Parameters:: path (str) – file path

write_lz4(path)

Write to file using lz4.

# Panics

Panics if the specified path is non-writeable (non-existent or missing permissions).

Parameters:: path (str) – file path

x_grid()

Get (unique) interpolation grid.

Returns:: `x_grid` – interpolation grid
Return type:: numpy.ndarray(float)

Grids

Grid interface.

class pineappl.grid.Grid(pid_basis, channels, orders, bins, convolutions, interpolations, kinematics, scale_funcs)

Bases: object

PyO3 wrapper to pineappl::grid::Grid.

bin_dimensions()

Get the dimension of the bins that define the observable.

Returns:: the dimention of the bins
Return type:: int

bin_limits()

Get the limits/edges of all the bins.

Returns:: limits/edges of the bins with shape (n_bins, n_dimension, 2)
Return type:: list(list(float))

bin_normalizations()

Extract the normalizations for each bin.

Returns:: bin normalizations
Return type:: numpy.ndarray

bin_slices()

Get the bin slices for this grid.

Returns:: a list of indices representing the slices
Return type:: list(list(int))

bins()

Return the number of bins.

Returns:: Number of bins
Return type:: int

bwfl()

Get the bin specifications for this grid.

Returns:: a PyBinsWithFillLimits object with containing the bin specifications
Return type:: PyBinsWithFillLimits

channels()

Extract channels.

Returns:: channels as tuples (List of PIDs, factor) (multiple tuples can be associated to the same contribution)
Return type:: list(list(tuple(list[float],int)))

convolutions

Get the type(s) of convolution(s) for the current Grid.

Returns:: One entry per convolution (type and PID).
Return type:: list of PyConv

convolve(pdg_convs, xfxs, alphas, order_mask=None, bin_indices=None, channel_mask=None, xi=None)

Convolve the grid with as many distributions.

Each xfx callable must return x * f(x, Q2) (LHAPDF style). The library uses f when combining with stored subgrid coefficients. Coefficients injected via pineappl.subgrid.ImportSubgridV1 are mainly external dumps defined to fold with f; they must use f, not x * f.

# Panics

Panics if Python callbacks fail, if the convolution cache cannot be matched to the grid, or if mask lengths are inconsistent with the grid when non-empty.

Parameters:

pdg_convs (list(PyConv)) – list containing the types of convolutions and PID
xfxs (list(callable)) – list of LHAPDF-like callables (pid, x, Q2) -> x * f
alphas (callable) – LHAPDF-like callable with argument Q2 returning alpha_s(Q2)
order_mask (numpy.ndarray(bool)) – Mask for selecting specific orders. The value True means the corresponding order is included. An empty list corresponds to all orders being enabled.
bin_indices (numpy.ndarray(int)) – A list with the indices of the corresponding bins that should be calculated. An empty list means that all bins should be calculated.
channel_mask (numpy.ndarray(bool)) – Mask for selecting specific channels. The value True means the corresponding channel is included. An empty list corresponds to all channels being enabled.
xi (list((float, float))) – A list with the scale variation factors that should be used to calculate scale-varied results. The first entry of a tuple corresponds to the variation of the renormalization scale, the second entry to the variation of the factorization scale. If only results for the central scale are need the list should contain (1.0, 1.0).

Returns:

cross sections for all bins, for each scale-variation tuple (first all bins, then the scale variation)

Return type:

numpy.ndarray(float)

dedup_channels(ulps)

Deduplicate channels

Parameters:: ulps (i64) – value of the tolerance to be used

delete_bins(bin_indices)

Delete bins.

Repeated bins and those exceeding the length are ignored.

Parameters:: bin_indices (list[int]) – list of indices of bins to be removed

delete_channels(channel_indices)

Deletes channels with the corresponding channel_indices. Repeated indices and indices larger or equal than the number of channels are ignored.

Parameters:: bin_indices (list[int]) – list of indices of bins to be removed

delete_orders(order_indices)

Delete orders with the corresponding order_indices. Repeated indices and indices larger or equal than the number of orders are ignored.

Parameters:: order_indices (list[int]) – list of indices of orders to be removed

evolve(slices, order_mask, xi, ren1, alphas)

Evolve the grid with as many EKOs as Convolutions.

# Panics

Panics when the operators returned by either slice have different dimensions than promised by the corresponding [OperatorSliceInfo].

# Errors

Raises error if either the operator or its info is incompatible with the Grid. Another error is raised if the iterator from slices themselves return an error.

Parameters:

slices (list(Generator(tuple(PyOperatorSliceInfo, PyReadOnlyArray4)))) – list of EKOs where each element is in turn a list of (PyOperatorSliceInfo, 4D array)
order_mask (numpy.ndarray(bool)) – boolean mask to activate orders
xi ((float, float)) – factorization and renormalization variation
ren1 (numpy.ndarray(float)) – list of renormalization scales
alphas (numpy.ndarray(float)) – list with alpha_s(Q2) at the corresponding entries of ren1

Returns:

produced FK table

Return type:

PyFkTable

evolve_info(order_mask)

Collect information for convolution with an evolution operator.

Parameters:: order_mask (numpy.ndarray(bool)) – boolean mask to activate orders
Returns:: evolution informations
Return type:: PyEvolveInfo

fill(order, observable, channel, ntuple, weight)

Add a point to the grid.

Parameters:

order (int) – order index
observable (float) – reference point (to be binned)
channel (int) – channel index
ntuple (list(float)) – list containing information on kinematics
weight (float) – cross section weight

fill_all_channels(order, observable, ntuple, weights)

Add a point to the grid for all channels.

Parameters:

order (int) – order index
observable (float) – reference point (to be binned)
ntuple (list(float)) – list containing information on kinematics
weights (np.array(float)) – cross section weights, one for each channels

fill_array(order, observables, channel, ntuples, weights)

Add an array to the grid.

Useful to avoid multiple python calls, leading to performance improvement.

Parameters:

order (int) – order index
observables (list(float)) – list of reference point (to be binned)
channel (int) – channel index
ntuples (list(list(float))) – list of ntuple kinematics
weights (np.array(float)) – cross section weight for all events

fix_convolution(conv_idx, xfx, xi=1.0)

Fix one of the convolutions in the Grid and return a new Grid with lower dimension.

# Panics

Panics if the wrapped Rust fix_convolution fails (for example invalid convolution index) or if the PDF callback raises or returns a non-float.

Parameters:

conv_idx (usize) – index of the convolution (zero-based)
xfx (callable) – LHAPDF-like (pid, x, Q2) -> x * f
xi (float)

interpolations

Get the interpolation specifications for the current grid.

Returns:: One interpolation spec per kinematic dimension.
Return type:: list of PyInterp

kinematics: Return the convention by which the Kinematics are encoded.

len()

Get the length/size of the bins.

Returns:: the size/length of the bins
Return type:: int

merge(other)

Merge with another grid.

# Errors

If the bin limits of self and other are different and if the bin limits of other can not be merged with self an error is returned.

merge_channel_factors(): Merge the factors of all the channels.

metadata

Get metadata values stored in the grid.

Returns:: key, value map
Return type:: dict

optimize(): Optimize the contents of the Grid.

optimize_using(flags)

Optimize the Grid using selected optimization flags.

Parameters:: flags (list[GridOptFlag]) – list of optimization flags.

orders()

Extract the available perturbative orders and scale variations.

Returns:: list with perturbative orders and scale variations
Return type:: list(PyOrder)

pid_basis: Return the convention by which the channels’ PIDS are encoded.

static read(path)

Load from file.

# Panics

Panics if the grid specified by the path is non-existent.

Parameters:: path (str) – file path
Returns:: grid
Return type:: PyGrid

removed_bin(index)

Get the removed bin using the index for this grid.

Parameters:: index (int) – index of the bin to be removed
Returns:: a Bin object from the removed index
Return type:: Bin

repair(): Repair the grid if it was written by bugged versions to disk.

rotate_pid_basis(pid_basis)

Rotate the Grid into the specified basis.

Parameters:: pid_basis (PyPidBasis) – PID basis of the resulting Grid

scale(factor)

Scale all subgrids.

Parameters:: factor (float) – scalar factor by which to scale

scale_by_bin(factors)

Scale subgrids bin by bin.

Parameters:: factors (list[float]) – bin-dependent factors by which to scale

scale_by_order(alphas, alpha, logxir, logxif, logxia, global_factor)

Scale subgrids by order.

Parameters:

alphas (float) – value of the strong coupling constant
alpha (float) – value of the electroweak constant
logxir (float) – value of the renormalization scale
logxif (float) – value of the factorization scale
logxia (float) – value of the fragmentation scale

scales: Return the convention by which the Scales are encoded.

set_bwfl(specs)

Set the bin specifications for this grid.

# Errors

Raises ValueError if the new bin layout is incompatible with this grid (for example bin count mismatch).

Parameters:: specs (PyBinsWithFillLimits) – the object to define the bin specs

set_metadata(key, value)

Set a metadata key-value pair in the grid.

Parameters:

key (str) – key
value (str) – value

set_subgrid(order, bin, channel, subgrid)

Set a subgrid.

Typical use with pineappl.subgrid.ImportSubgridV1: load coefficient tables dumped from outside PineAPPL that are meant to be convolved with ``f``. Those coefficients must use the parton f(x) convention, not x * f(x).

Parameters:

order (int) – order index
bin (int) – bin index
channel (int) – channel index
subgrid (PySubgridEnum) – subgrid object

split_channels(): Splits the grid such that each channel contains only a single tuple of PIDs.

subgrid(order, bin, channel): Retrieve a subgrid.

write(path)

Write to file.

# Panics

Panics if the specified path to write the grid is non-existent or requires permission.

Parameters:: path (str) – file path

write_lz4(path)

Write to compressed file.

# Panics

Panics if the specified path to write the grid is non-existent or requires permission.

Parameters:: path (str) – file path

class pineappl.grid.GridOptFlag

Bases: object

PyO3 wrapper for pineappl::grid::GridOptFlags.

MergeSameChannels = GridOptFlag.MergeSameChannels

OptimizeNodes = GridOptFlag.OptimizeNodes

OptimizeSubgridType = GridOptFlag.OptimizeSubgridType

StaticScaleDetection = GridOptFlag.StaticScaleDetection

StripEmptyChannels = GridOptFlag.StripEmptyChannels

StripEmptyOrders = GridOptFlag.StripEmptyOrders

SymmetrizeChannels = GridOptFlag.SymmetrizeChannels

Interpolation

Interpolation submodule.

class pineappl.interpolation.Interp(min, max, nodes=None, order=None, reweight_meth=None, map=None, interpolation_meth=None)

Bases: object

PyO3 wrapper to pineappl::interpolation::Interp.

class pineappl.interpolation.InterpolationMethod

Bases: object

PyO3 wrapper to pineappl::interpolation::InterpMeth.

Lagrange = InterpolationMethod.Lagrange

class pineappl.interpolation.MappingMethod

Bases: object

PyO3 wrapper to pineappl::interpolation::Map.

ApplGridF2 = MappingMethod.ApplGridF2

ApplGridH0 = MappingMethod.ApplGridH0

class pineappl.interpolation.ReweightingMethod

Bases: object

PyO3 wrapper to pineappl::interpolation::ReweightMeth.

ApplGridX = ReweightingMethod.ApplGridX

NoReweight = ReweightingMethod.NoReweight

PID Basis

PIDs interface.

class pineappl.pids.PidBasis

Bases: object

PyO3 wrapper to pineappl::pids::PidBasis.

Evol = PidBasis.Evol

Pdg = PidBasis.Pdg

Subgrids

Subgrid interface.

ImportSubgridV1 is for coefficient tables dumped from outside PineAPPL, to be convolved with f; array values use the f(x) convention, not x*f(x). Grid.convolve uses LHAPDF x*f callbacks (see pineappl issue 388).

class pineappl.subgrid.ImportSubgridV1(array, node_values)

Bases: object

Sparse subgrid for coefficient functions dumped from outside PineAPPL, to be convolved with f.

Typical use: load tabulated coefficients from another code; they must be defined to fold with parton f(x), not x * f(x). Non-zero entries in array follow that f convention. Grid .convolve still expects LHAPDF-style callables that return x * f; the core library divides by x when building the luminosity. See the submodule docstring and issue 388.

into(): Ensures that the subgrid has type PySubgridEnum.

class pineappl.subgrid.SubgridEnum

Bases: object

PyO3 wrapper to pineappl::subgrid::SubgridEnum

into(): Clone.

is_empty(): Check whether the subgrid is empty (contains no non-zero entries).

node_values: Get the values of nodes used for the subgrids

scale(factor)

Scale the subgrid by factor.

Parameters:: factor (float) – scaling factor

shape: Get the shape of the subgrids

to_array(shape): Return the dense array of the subgrid.