PineAPPL’s Python API

PyO3 Python module that contains all exposed classes from Rust.

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.

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 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 list(PyConv):

list of convolution type with the corresponding PIDs

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

Convolve the FK table with as many distributions.

# Panics TODO

Parameters:

  • pdg_convs (list(PyConv)) – list containing the types of convolutions and PID

  • xfxs (list(callable)) – list of lhapdf-like callable with arguments pid, x, Q2 returning x*pdf

  • 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 TODO

Parameteters

pathstr

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.

# Errors TODO

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)

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 list(PyConv):

list of convolution type with the corresponding PIDs

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

Convolve the grid with as many distributions.

# Panics TODO

Parameters:

  • pdg_convs (list(PyConv)) – list containing the types of convolutions and PID

  • xfxs (list(callable)) – list of lhapdf-like callable with arguments pid, x, Q2 returning x*pdf

  • alphas (callable) – lhapdf like callable with arguments Q2 returning \(\alpha_s\)

  • 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.

# Panics TODO

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)\) for the process scales

Returns:

produced FK table

Return type:

PyFkTable

evolve_info(order_mask)

Collect information for convolution with an evolution operator.

# Panics TODO

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

TODO

Parameters:

  • conv_idx (usize) – index of the convolution (zero-based)

  • xfxs (callable) – lhapdf-like callable with arguments pid, x, Q2 returning x*pdf

  • xi (float)

interpolations

Get the interpolation specifications for the current grid.

Returns list(PyInterp):

list of interpolation specifications

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.

# Panics TODO

# 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.

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.

# Panics TODO

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.

# Panics TODO

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 TODO

Parameters:

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

set_metadata(key, value)

Set a metadata key-value pair in the grid.

# Panics TODO

Parameters:

  • key (str) – key

  • value (str) – value

set_subgrid(order, bin, channel, subgrid)

Set a subgrid.

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

Subgrid interface.

class pineappl.subgrid.ImportSubgridV1(array, node_values)

Bases: object

PyO3 wrapper to pineappl::subgrid::ImportSubgridV1.

into()

Ensures that the subgrid has type PySubgridEnum.

class pineappl.subgrid.SubgridEnum

Bases: object

PyO3 wrapper to pineappl::subgrid::SubgridEnum

into()

Clone.

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.