UMAMI API¶

Typedefs

typedef void *UmamiHandle: Implementation-defined pointer to a matrix element instance

Enums

enum UmamiStatus

Values:

enumerator UMAMI_SUCCESS: operation was executed successfully

enumerator UMAMI_ERROR: an unspecified error

enumerator UMAMI_ERROR_NOT_IMPLEMENTED: operation not implemented

enumerator UMAMI_ERROR_UNSUPPORTED_INPUT: the provided input key is not supported by this matrix element implementation

enumerator UMAMI_ERROR_UNSUPPORTED_OUTPUT: the provided output key is not supported by this matrix element implementation

enumerator UMAMI_ERROR_UNSUPPORTED_META: the provided metadata key is not supported by this matrix element implementation

enumerator UMAMI_ERROR_MISSING_INPUT: a mandatory matrix element input was not provided

enum UmamiDevice

Values:

enumerator UMAMI_DEVICE_CPU

enumerator UMAMI_DEVICE_CUDA

enumerator UMAMI_DEVICE_HIP

enum UmamiMetaKey

Values:

enumerator UMAMI_META_DEVICE: UmamiDevice specifying the type of device

enumerator UMAMI_META_PARTICLE_COUNT: int specifying the number of external particles

enumerator UMAMI_META_DIAGRAM_COUNT: int specifying the number of Feynman diagrams

enumerator UMAMI_META_HELICITY_COUNT: int specifying the number of helicities

enumerator UMAMI_META_COLOR_COUNT: int specifying the number of colors

enum UmamiInputKey

Values:

enumerator UMAMI_IN_MOMENTA: momenta of the external legs, type: double, shape: (particle count, 4)

enumerator UMAMI_IN_ALPHA_S: value for the strong coupling, type: double, shape: ()

enumerator UMAMI_IN_FLAVOR_INDEX: flavor index, type: int, shape: ()

enumerator UMAMI_IN_RANDOM_COLOR: random number for color selection, type: double, shape: ()

enumerator UMAMI_IN_RANDOM_HELICITY: random number for helicity selection, type: double, shape: ()

enumerator UMAMI_IN_RANDOM_DIAGRAM: random number for diagram selection, type: double, shape: ()

enumerator UMAMI_IN_HELICITY_INDEX: externally selected helicity index, type: int, shape: ()

enumerator UMAMI_IN_DIAGRAM_INDEX: externally selected diagram index, type: int, shape: ()

enum UmamiOutputKey

Values:

enumerator UMAMI_OUT_MATRIX_ELEMENT: value of the matrix element, type: double, shape: ()

enumerator UMAMI_OUT_DIAGRAM_AMP2: selected color index, type: double, shape: (diagram count)

enumerator UMAMI_OUT_COLOR_INDEX: selected color index, type: int, shape: ()

enumerator UMAMI_OUT_HELICITY_INDEX: selected helicity index, type: int, shape: ()

enumerator UMAMI_OUT_DIAGRAM_INDEX: selected diagram index, type: int, shape: ()

enumerator UMAMI_OUT_GPU_STREAM: CUDA or HIP stream for asynchronous execution. Listed as an output as it is a mutable pointer

Functions

UmamiStatus umami_get_meta(UmamiMetaKey meta_key, void *result)

Retrieve metadata about the implemented matrix element

Parameters:

meta_key – key specifying the type of metadata to be retrieved
result – pointer to store the result. It’s type depends on the metadata key

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_initialize(UmamiHandle *handle, char const *param_card_path)

Creates an instance of the matrix element. Each instance is independent, so thread safety can be achieved by creating a separate one for every thread.

Parameters:

handle – pointer to an instance of the subprocess. Has to be cleaned up by the caller with free_subprocess.
param_card_path – path to the parameter file

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_set_parameter(UmamiHandle handle, char const *name, double parameter_real, double parameter_imag)

Sets the value of a model parameter

Parameters:

handle – handle of a matrix element instance
name – name of the parameter
parameter_real – real part of the parameter value
parameter_imag – imaginary part of the parameter value. Ignored for real valued parameters.

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_get_parameter(UmamiHandle handle, char const *name, double *parameter_real, double *parameter_imag)

Retrieves the value of a model parameter

Parameters:

handle – handle of a matrix element instance
name – name of the parameter
parameter_real – pointer to double to return real part of the parameter value
parameter_imag – pointer to double to return imaginary part of the parameter value. Ignored for real-valued parameters (i.e. you may pass a null pointer)

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_matrix_element(UmamiHandle handle, size_t count, size_t stride, size_t offset, size_t input_count, UmamiInputKey const *input_keys, void const *const *inputs, size_t output_count, UmamiOutputKey const *output_keys, void *const *outputs)

Evaluates the matrix element as a function of the given inputs, filling the requested outputs. Unless otherwise specified, all inputs and outputs have a column-major memory layout and have a batch dimension that is contiguous in memory.

Parameters:

handle – handle of a matrix element instance
count – number of events to evaluate the matrix element for
stride – stride of the batch dimension of the input and output arrays to simplify parallel execution on CPUs, see memory layout
offset – offset of the event index
input_count – number of inputs to the matrix element
input_keys – pointer to an array of input keys, length input_count
inputs – pointer to an array of void pointers to the inputs. The type of the inputs depends on the input key
output_count – number of outputs to the matrix element
output_keys – pointer to an array of output keys, length output_count
outputs – pointer to an array of void pointers to the outputs. The type of the outputs depends on the output key. The caller is responsible for allocating memory for the outputs.

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_free(UmamiHandle handle)

Frees matrix element instance

Parameters:: handle – handle of a matrix element instance

Variables

const int UMAMI_MAJOR_VERSION = 1: Major version number of the UMAMI interface. If the major version is the same between caller and implementation, binary compatibility is ensured.

const int UMAMI_MINOR_VERSION = 0: Minor version number of the UMAMI interface. Between minor versions, new keys for errors, devices, metadata, inputs and outputs can be added.