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.
- Type for reading and accessing subgrids.
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
. - Delete a grid previously created with
pineappl_grid_new
. - Fills
buffer
with the q2-slice for the indexq2_slice
of the grid for the specifiedorder
,bin
, andlumi
. - 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
. - Creates a new and empty grid. The creation requires four different sets of parameters:
- Write into
tuple
the lower and upper limit of filled q2 slices for the grid with the specified indices. The last slice that is filled is one minus the upper limit. - Optimizes the grid representation for space efficiency.
- Return the number of orders in
grid
. - Write the order parameters of
grid
intoorder_params
. - Read a
PineAPPL
grid from a file with namefilename
. - This function takes replaces the subgrid in
grid
with the corresponding indicesorder
,bin
andlumi
with the one given insubgrid
. Ifsubgrid
is the null pointer, the specied subgrid is replaced with an empty one. - 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.
- 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. - Deletes a subgrid created with
pineappl_subgrid_new2
. Ifsubgrid
is the null pointer, nothing is done. - Imports
slice
for the given index intosubgrid
. - Creates a new subgrid, which can be filled with
pineappl_subgrid_import_mu2_slice
. The arraymu2_grid
must contain the (squared) values of the renormalization and then the factorization scale, such that twice the value ofmu2_grid_len
gives the length of the array.