Crate pineappl_capi
source ·Expand description
The C-language interface for PineAPPL
.
The PineAPPL
Application Programming Interface for the C language (CAPI) defines types and
functions that allow PineAPPL
to be used without having to write Rust code, and instead
offering
- C or C++, or
- Fortran as programming languages. Fortran is supported using the
iso_c_binding
module to wrap CAPI’s functions (see the Fortran example in the repository).
Note that the CAPI only defines a subset of functionality available in the Rust module, which is extended on an as-needed basis. If you happen to miss a function please open a new issue on the github page.
§Using and linking the CAPI
To use PineAPPL
’s CAPI you must include its header pineappl_capi.h
. To successfully build
your program, you should rely on pkgconf
or pkg-conf
, as follows:
pkg-config --cflags pineappl_capi
pkg-config --libs pineappl_capi
This will read PineAPPL
’s .pc
file and print the neccessary CFLAGS
(--cflags
) and
linker flags (--libs
). This procedure is supported by many build systems, such as
- Autoconf/Automake, using the
PKG_CHECK_MODULES
macro, see the Autotools mythbuster page for correct usage, - CMake, using
FindPkgConfig
and - meson, using
dependency
; it usually suffices to writedependency('pineappl_capi')
.
§Strings and other types
Strings used in this library are have the Rust type *const c_char
or *mut c_char
and
correspond to the C types const char*
and char*
, respectively. The strings are assumed to
be encoded using UTF-8, which Rust uses internally.
All other built-in types in Rust (f64
, usize
, i32
, u32
, …) correspond to types in C
as defined by the translation tables of cbindgen. If in doubt, consult the generated header
pineappl_capi.h
.
Structs§
- Key-value storage for passing optional information during grid creation with
pineappl_grid_new
. - Type for defining a luminosity function.
Functions§
- Returns the number of bins in
grid
. - Returns the number of dimensions of the bins this grid has.
- Write the left limits for the specified dimension into
left
. - Write the right limits for the specified dimension into
right
. - Stores the bin sizes of
grid
inbin_sizes
. - Returns a cloned object of
grid
. - Convolutes the specified grid with the PDF
xfx
, which is the PDF for a hadron with the PDG idpdg_id
, and strong couplingalphas
. These functions must evaluate the PDFs for the givenx
andq2
for the parton with the given PDG id,pdg_id
, and return the result. Note that the value must be the PDF multiplied with its argumentx
. The value of the pointerstate
provided to these functions is the same one given to this function. The parameterorder_mask
must be as long as there are perturbative orders contained ingrid
and is used to selectively disable (false
) or enable (true
) individual orders. Iforder_mask
is set toNULL
, all orders are active. The parameterlumi_mask
can be used similarly, but must be as long as the luminosity functiongrid
was created with has entries, orNULL
to enable all luminosities. The valuesxi_ren
andxi_fac
can be used to vary the renormalization and factorization from its central value, which corresponds to1.0
. After convolution of the grid with the PDFs the differential cross section for each bin is written intoresults
. - Convolutes the specified grid with the PDFs
xfx1
andxfx2
, which are the PDFs of hadrons with PDG idspdg_id1
andpdg_id2
, respectively, and strong couplingalphas
. These functions must evaluate the PDFs for the givenx
andq2
for the parton with the given PDG id,pdg_id
, and return the result. Note that the value must be the PDF multiplied with its argumentx
. The value of the pointerstate
provided to these functions is the same one given to this function. The parameterorder_mask
must be as long as there are perturbative orders contained ingrid
and is used to selectively disable (false
) or enable (true
) individual orders. Iforder_mask
is set toNULL
, all orders are active. The parameterlumi_mask
can be used similarly, but must be as long as the luminosity functiongrid
was created with has entries, orNULL
to enable all luminosities. The valuesxi_ren
andxi_fac
can be used to vary the renormalization and factorization from its central value, which corresponds to1.0
. After convolution of the grid with the PDFs the differential cross section for each bin is written intoresults
. - Try to deduplicate channels of
grid
by detecting pairs of them that contain the same subgrids. The numerical equality is tested using a tolerance ofulps
, given in units of least precision. - Delete a grid previously created with
pineappl_grid_new
. - Fill
grid
for the given momentum fractionsx1
andx2
, at the scaleq2
for the given value of theorder
,observable
, andlumi
withweight
. - Fill
grid
for the given momentum fractionsx1
andx2
, at the scaleq2
for the given value of theorder
andobservable
withweights
. The parameter of weight must contain a result for entry of the luminosity function the grid was created with. - Fill
grid
with as many points as indicated bysize
. - Return the value for
key
stored ingrid
. Ifkey
isn’t found,NULL
will be returned. After usage the string must be deallocated usingpineappl_string_delete
. - Return the luminosity function of
grid
. - Merges
other
intogrid
and subsequently deletesother
. - Merges the bins of corresponding to the indices from the half-open interval
[from, to]
into a single bin. - Creates a new and empty grid. The creation requires four different sets of parameters:
- Optimizes the grid representation for space efficiency.
- Optimizes the grid representation for space efficiency. The parameter
flags
determines which optimizations are applied, seeGridOptFlags
. - Return the number of orders in
grid
. - Write the order parameters of
grid
intoorder_params
. - Read a
PineAPPL
grid from a file with namefilename
. - Scale all grids in
grid
byfactor
. - Scales each subgrid by a bin-dependent factor given in
factors
. If a bin does not have a corresponding entry infactors
it is not rescaled. Iffactors
has more entries than there are bins the superfluous entries do not have an effect. - Scales each subgrid by a factor which is the product of the given values
alphas
,alpha
,logxir
, andlogxif
, each raised to the corresponding powers for each subgrid. In addition, every subgrid is scaled by a factorglobal
independently of its order. - Sets an internal key-value pair for the grid.
- Sets a remapper for the grid. This can be used to ‘upgrade’ one-dimensional bin limits to N-dimensional ones. The new bin limits must be given in the form of tuples giving the left and right limits, and a tuple for each dimension.
- Splits the grid such that the luminosity function contains only a single combination per channel.
- Write
grid
to a file with namefilename
. Iffilename
ends in.lz4
the grid is automatically LZ4 compressed. - Get the boolean-valued parameter with name
key
stored inkey_vals
. - Delete the previously created object pointed to by
key_vals
. - Get the double-valued parameter with name
key
stored inkey_vals
. - Get the string-valued parameter with name
key
stored inkey_vals
. - Return a pointer to newly-created
pineappl_keyval
object. - Set the double-valued parameter with name
key
tovalue
inkey_vals
. - Set the double-valued parameter with name
key
tovalue
inkey_vals
. - Set the int-valued parameter with name
key
tovalue
inkey_vals
. - Set the string-valued parameter with name
key
tovalue
inkey_vals
. - Get the int-valued parameter with name
key
stored inkey_vals
. - Adds a linear combination of initial states to the luminosity function
lumi
. - Returns the number of combinations of the luminosity function
lumi
for the specified entry. - Returns the number of channel for the luminosity function
lumi
. - Delete luminosity function previously created with
pineappl_lumi_new
. - Read out the channel with index
entry
of the luminosity functionlumi
. The PDG ids and factors will be copied intopdg_ids
andfactors
. - Creates a new luminosity function and returns a pointer to it. If no longer needed, the object should be deleted using
pineappl_lumi_delete
. - Deletes a string previously allocated by
pineappl_grid_key_value
. Ifstring
is aNULL
pointer this function does nothing.