Crate pineappl_capi

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 write dependency('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§

Channels: Type for defining a Channel function.
Interp: Type for defining the interpolation object
KeyVal: Key-value storage for passing optional information during grid creation with pineappl_grid_new.
Lumi: Type for defining a luminosity function.
OperatorInfo: Type for defining the Operator info.

Constants§

PINEAPPL_GOF_MERGE_SAME_CHANNELS: TODO
PINEAPPL_GOF_OPTIMIZE_NODES: TODO
PINEAPPL_GOF_OPTIMIZE_SUBGRID_TYPE: TODO
PINEAPPL_GOF_STRIP_EMPTY_CHANNELS: TODO
PINEAPPL_GOF_STRIP_EMPTY_ORDERS: TODO
PINEAPPL_GOF_SYMMETRIZE_CHANNELS: TODO

Functions§

pineappl_channels_add^⚠: Adds a generalized linear combination of initial states to the Luminosity.
pineappl_channels_combinations^⚠: An exact duplicate of pineappl_lumi_combinations to make naming (lumi -> channel) consistent.
pineappl_channels_count^⚠: An exact duplicate of pineappl_lumi_count to make naming (lumi -> channel) consistent.
pineappl_channels_delete: An exact duplicate of pineappl_lumi_delete to make naming (lumi -> channel) consistent.
pineappl_channels_entry^⚠: Read out the channel with index entry of the given channels. The PDG ids and factors will be copied into pdg_ids and factors.
pineappl_channels_new: An exact duplicate of pineappl_lumi_new to make naming (lumi -> channel) consistent. should be deleted using pineappl_channels_delete.
pineappl_fktable_optimize^⚠: Optimize the size of this FK-table by removing heavy quark flavors assumed to be zero.
pineappl_grid_bin_count^⚠: Returns the number of bins in grid.
pineappl_grid_bin_dimensions^⚠: Returns the number of dimensions of the bins this grid has.
pineappl_grid_bin_limits_left^⚠: Write the left limits for the specified dimension into left.
pineappl_grid_bin_limits_right^⚠: Write the right limits for the specified dimension into right.
pineappl_grid_bin_normalizations^⚠: Stores the bin sizes of grid in bin_sizes.
pineappl_grid_channels^⚠: An exact duplicate of pineappl_grid_lumi to make naming (lumi -> channel) consistent.
pineappl_grid_clone^⚠: Returns a cloned object of grid.
pineappl_grid_conv_types^⚠: Get the type of convolutions for this Grid.
pineappl_grid_convolute_with_one^⚠Deprecated: Wrapper for pineappl_grid_convolve_with_one.
pineappl_grid_convolute_with_two^⚠Deprecated: Wrapper for pineappl_grid_convolve_with_two.
pineappl_grid_convolutions_len^⚠: Get the number of convolutions for a given Grid.
pineappl_grid_convolve^⚠: A generalization of the convolution function for Grids.
pineappl_grid_convolve_with_one^⚠: Convolutes the specified grid with the PDF 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 channel_mask can be used similarly, but must be as long as the channels grid was created with has entries, or NULL to enable all channels. 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_convolve_with_two^⚠: Convolutes the specified grid with the PDFs 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 channel_mask can be used similarly, but must be as long as the channels grid was created with has entries, or NULL to enable all channels. 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_dedup_channels^⚠: Try to deduplicate channels of grid by detecting pairs of them that contain the same subgrids. The numerical equality is tested using a tolerance of ulps, given in units of least precision.
pineappl_grid_delete: Delete a grid previously created with pineappl_grid_new.
pineappl_grid_delete_bins^⚠: Deletes bins with the corresponding bin_indices. Repeated indices and indices larger or equal the bin length are ignored.
pineappl_grid_evolve^⚠: Evolve a grid with an evolution operator and dump the resulting FK table.
pineappl_grid_evolve_info^⚠: Get the values of the parameters contained in evolve info.
pineappl_grid_evolve_info_shape^⚠: Get the shape of the objects represented in the evolve info.
pineappl_grid_fill^⚠Deprecated: Fill 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.
pineappl_grid_fill2^⚠: Similar to pineappl_grid_fill but accepts any given momentum fractions {x1, …,xn} at various energy scalesfor the given value of the order, observable, and lumi with weight.
pineappl_grid_fill_all^⚠Deprecated: Fill 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.
pineappl_grid_fill_all2^⚠: Similar to pineappl_grid_fill_all but accepts any given momentum fractions {x1, …,xn} at various energy scalesfor the given value of the order, observable, and lumi with weight.
pineappl_grid_fill_array^⚠Deprecated: Fill grid with as many points as indicated by size.
pineappl_grid_fill_array2^⚠: Similar to pineappl_grid_fill_array but accepts any given momentum fractions {x1, …,xn} at various energy scalesfor the given value of the order, observable, and lumi with weight.
pineappl_grid_key_value^⚠Deprecated: Return the value for key stored in grid. If key isn’t found, NULL will be returned. After usage the string must be deallocated using pineappl_string_delete.
pineappl_grid_kinematics_len^⚠: Get the number of different kinematics for a given Grid.
pineappl_grid_lumi^⚠Deprecated: Return the luminosity function of grid.
pineappl_grid_merge_and_delete^⚠: Merges other into grid and subsequently deletes other.
pineappl_grid_merge_bins^⚠: Merges the bins of corresponding to the indices from the half-open interval [from, to] into a single bin.
pineappl_grid_new^⚠Deprecated: Creates a new and empty grid. The creation requires four different sets of parameters:
pineappl_grid_new2^⚠: Creates a new and empty grid that can accept any number of convolutions. The creation requires the following different sets of parameters:
pineappl_grid_optimize^⚠: Optimizes the grid representation for space efficiency.
pineappl_grid_optimize_using^⚠: Optimizes the grid representation for space efficiency. The parameter flags determines which optimizations are applied, see GridOptFlags.
pineappl_grid_order_count^⚠: Return the number of orders in grid.
pineappl_grid_order_params^⚠Deprecated: Write the order parameters of grid into order_params.
pineappl_grid_order_params2^⚠: An extension of pineappl_grid_order_params that accounts for the order of the fragmentation logs.
pineappl_grid_pid_basis^⚠: Get the particle ID basis of a Grid.
pineappl_grid_read^⚠: Read a PineAPPL grid from a file with name filename.
pineappl_grid_rotate_pid_basis^⚠: Change the particle ID basis of a given Grid.
pineappl_grid_scale^⚠: Scale all grids in grid by factor.
pineappl_grid_scale_by_bin^⚠: Scales each subgrid by a bin-dependent factor given in factors. If a bin does not have a corresponding entry in factors it is not rescaled. If factors has more entries than there are bins the superfluous entries do not have an effect.
pineappl_grid_scale_by_order^⚠: Scales each subgrid by a factor which is the product of the given values 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.
pineappl_grid_set_key_value^⚠Deprecated: Sets an internal key-value pair for the grid.
pineappl_grid_set_remapper^⚠: 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.
pineappl_grid_split_channels^⚠: Similar to pineappl_grid_split_channels.
pineappl_grid_split_lumi^⚠Deprecated: Splits the grid such that the luminosity function contains only a single combination per channel.
pineappl_grid_subgrid_array^⚠: Get the subgrid for a given bin, channel, and order.
pineappl_grid_subgrid_node_values^⚠: Get the nodes of the subgrid.
pineappl_grid_subgrid_shape^⚠: Get the shape of a subgrid for a given bin, channel, and order.
pineappl_grid_write^⚠: Write grid to a file with name filename. If filename ends in .lz4 the grid is automatically LZ4 compressed.
pineappl_keyval_bool^⚠Deprecated: Get the boolean-valued parameter with name key stored in key_vals.
pineappl_keyval_deleteDeprecated: Delete the previously created object pointed to by key_vals.
pineappl_keyval_double^⚠Deprecated: Get the double-valued parameter with name key stored in key_vals.
pineappl_keyval_int^⚠Deprecated: Get the string-valued parameter with name key stored in key_vals.
pineappl_keyval_newDeprecated: Return a pointer to newly-created pineappl_keyval object.
pineappl_keyval_set_bool^⚠Deprecated: Set the double-valued parameter with name key to value in key_vals.
pineappl_keyval_set_double^⚠Deprecated: Set the double-valued parameter with name key to value in key_vals.
pineappl_keyval_set_int^⚠Deprecated: Set the int-valued parameter with name key to value in key_vals.
pineappl_keyval_set_string^⚠Deprecated: Set the string-valued parameter with name key to value in key_vals.
pineappl_keyval_string^⚠Deprecated: Get the int-valued parameter with name key stored in key_vals.
pineappl_lumi_add^⚠Deprecated: Adds a linear combination of initial states to the luminosity function lumi.
pineappl_lumi_combinations^⚠Deprecated: Returns the number of combinations of the luminosity function lumi for the specified entry.
pineappl_lumi_count^⚠Deprecated: Returns the number of channel for the luminosity function lumi.
pineappl_lumi_deleteDeprecated: Delete luminosity function previously created with pineappl_lumi_new.
pineappl_lumi_entry^⚠Deprecated: Read out the channel with index entry of the luminosity function lumi. The PDG ids and factors will be copied into pdg_ids and factors.
pineappl_lumi_newDeprecated: Creates a new luminosity function and returns a pointer to it. If no longer needed, the object should be deleted using pineappl_lumi_delete.
pineappl_string_delete^⚠: Deletes a string previously allocated by pineappl_grid_key_value. If string is a NULL pointer this function does nothing.

Type Aliases§

OperatorCallback: Type alias for the operator callback