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 one to use PineAPPL
without having to write Rust code, and instead
using
- C or C++ (see the C++ example in the repository).
- Fortran can be used as well, 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 have to 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
All strings used in this library, denoted with the Rust type *const c_char
or *mut c_char
,
which correspond to the C types const char*
and char*
, respectively, are assumed to be
encoded using UTF-8, which Rust uses internally. The conversions are performed using
CStr::to_string_lossy
, which you can consult on how strings are converted.
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
pineappl_grid_new
.Functions
grid
.left
.right
.grid
in bin_sizes
.grid
.xfx
, which is the PDF for a hadron with the PDG id
pdg_id
, and strong coupling alphas
. These functions must evaluate the PDFs for the given
x
and q2
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 argument x
. The value of the pointer state
provided to these functions is the same one given to this function. The parameter order_mask
must be as long as there are perturbative orders contained in grid
and is used to selectively
disable (false
) or enable (true
) individual orders. If order_mask
is set to NULL
, all
orders are active. The parameter lumi_mask
can be used similarly, but must be as long as the
luminosity function grid
was created with has entries, or NULL
to enable all luminosities.
The values xi_ren
and xi_fac
can be used to vary the renormalization and factorization from
its central value, which corresponds to 1.0
. After convolution of the grid with the PDFs the
differential cross section for each bin is written into results
.xfx1
and xfx2
, which are the PDFs of hadrons
with PDG ids pdg_id1
and pdg_id2
, respectively, and strong coupling alphas
. These
functions must evaluate the PDFs for the given x
and q2
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
argument x
. The value of the pointer state
provided to these functions is the same one
given to this function. The parameter order_mask
must be as long as there are perturbative
orders contained in grid
and is used to selectively disable (false
) or enable (true
)
individual orders. If order_mask
is set to NULL
, all orders are active. The parameter
lumi_mask
can be used similarly, but must be as long as the luminosity function grid
was
created with has entries, or NULL
to enable all luminosities. The values xi_ren
and
xi_fac
can be used to vary the renormalization and factorization from its central value,
which corresponds to 1.0
. After convolution of the grid with the PDFs the differential cross
section for each bin is written into results
.pineappl_grid_new
.buffer
with the q2-slice for the index q2_slice
of the grid for the specified
order
, bin
, and lumi
.grid
for the given momentum fractions x1
and x2
, at the scale q2
for the given
value of the order
, observable
, and lumi
with weight
.grid
for the given momentum fractions x1
and x2
, at the scale q2
for the given
value of the order
and observable
with weights
. The parameter of weight must contain a
result for entry of the luminosity function the grid was created with.grid
with as many points as indicated by size
.key
stored in grid
. If key
isn’t found, NULL
will be returned.
After usage the string must be deallocated using pineappl_string_delete
.grid
.other
into grid
and subsequently deletes other
.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.grid
.grid
into order_params
.PineAPPL
grid from a file with name filename
.grid
with the corresponding indices order
,
bin
and lumi
with the one given in subgrid
. If subgrid
is the null pointer, the specied
subgrid is replaced with an empty one.grid
by factor
.alphas
, alpha
,
logxir
, and logxif
, each raised to the corresponding powers for each subgrid. In addition,
every subgrid is scaled by a factor global
independently of its order.grid
to a file with name filename
. If filename
ends in .lz4
the grid is
automatically LZ4 compressed.key
stored in key_vals
.key_vals
.key
stored in key_vals
.key
stored in key_vals
.pineappl_keyval
object.key
to value
in key_vals
.key
to value
in key_vals
.key
to value
in key_vals
.key
to value
in key_vals
.key
stored in key_vals
.lumi
.lumi
for the specified entry.lumi
.pineappl_lumi_new
.entry
of the luminosity function lumi
. The PDG ids and
factors will be copied into pdg_ids
and factors
.pineappl_lumi_delete
.pineappl_grid_key_value
. If string
is a NULL
pointer this function does nothing.pineappl_subgrid_new2
. If subgrid
is the null pointer,
nothing is done.slice
for the given index into subgrid
.pineappl_subgrid_import_mu2_slice
. The
array mu2_grid
must contain the (squared) values of the renormalization and then the
factorization scale, such that twice the value of mu2_grid_len
gives the length of the array.