UMAMI API

Defines

UMAMI_MAJOR_VERSION

Major version number of the UMAMI interface.

If the major version is the same between caller and implementation, binary compatibility is ensured.

UMAMI_MINOR_VERSION

Minor version number of the UMAMI interface.

Between minor versions, new keys for errors, devices, metadata, inputs and outputs can be added.

UMAMI_INPUT_KEY_COUNT

Number of values in UmamiInputKey

UMAMI_OUTPUT_KEY_COUNT

Number of values in UmamiOutputKey

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_UNINITIALIZED_META

the meta_key was not yet initialized

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

enumerator UMAMI_META_MASSES

double array of length particle count: the external-leg masses (GeV)

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: unsigned int, shape: ()

enumerator UMAMI_IN_CHANNEL_INDEX

externally selected channel index, type: unsigned int, shape: ()

enumerator UMAMI_IN_PARTICLE_COUNT

number of external legs, type: int, shape: ()

enumerator UMAMI_IN_PDG_IDS

PDG ids of the external legs, type: int, shape: (particle count)

enumerator UMAMI_IN_MOMENTUM_FRACTION

momentum fraction of an incoming parton, type: double, shape: ()

enumerator UMAMI_IN_SCALE

energy scale, e.g.

the factorization scale, type: double, shape: ()

enumerator UMAMI_IN_PDG_ID

PDG id of a single parton, type: int, shape: ()

enumerator UMAMI_IN_BEAM_INDEX

index of the beam (0 or 1), type: int, shape: ()

enum UmamiOutputKey

Values:

enumerator UMAMI_OUT_MATRIX_ELEMENT

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

enumerator UMAMI_OUT_DIAGRAM_AMP2

squared amplitudes of the diagrams, 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

enumerator UMAMI_OUT_CUT

value of a custom cut, 0 rejects the event, type: double, shape: ()

enumerator UMAMI_OUT_REN_SCALE

custom renormalization scale, type: double, shape: ()

enumerator UMAMI_OUT_FACT_SCALE_1

custom factorization scale of the first incoming particle, type: double, shape: ()

enumerator UMAMI_OUT_FACT_SCALE_2

custom factorization scale of the second incoming particle, type: double, shape: ()

enumerator UMAMI_OUT_PDF

value x f(x, Q) of a custom parton density, type: double, shape: ()

enumerator UMAMI_OUT_BIAS

value of a custom event bias, type: double, shape: ()

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_supported_inputs(bool const **supported, int *count)

Reports which input keys can be passed to this matrix element implementation, to be written by whoever implements the UMAMI interface.

Implementing this function is optional; a caller that fails to resolve it should treat it as unavailable.

Parameters:

  • supported – pointer set on return to an implementation-owned array of booleans, where element i indicates whether the input key with numeric value i (see UmamiInputKey) is accepted by this implementation.

  • count – pointer set on return to the number of elements in *supported, reflecting the number of UmamiInputKey values known to this implementation. A caller built against a newer header should treat any key index beyond *count as not supported.

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_required_inputs(bool const **required, int *count)

Reports which input keys must be passed to this matrix element implementation for umami_matrix_element to succeed, to be written by whoever implements the UMAMI interface.

This is a subset of the keys reported by umami_supported_inputs. Implementing this function is optional; a caller that fails to resolve it should treat it as unavailable.

Parameters:

  • required – pointer set on return to an implementation-owned array of booleans, where element i indicates whether the input key with numeric value i (see UmamiInputKey) is mandatory for this implementation.

  • count – pointer set on return to the number of elements in *required. A caller built against a newer header should treat any key index beyond *count as not required.

Returns:

UMAMI_SUCCESS on success, error code otherwise

UmamiStatus umami_supported_outputs(bool const **supported, int *count)

Reports which output keys can be requested from this matrix element implementation, to be written by whoever implements the UMAMI interface.

Implementing this function is optional; a caller that fails to resolve it should treat it as unavailable.

Parameters:

  • supported – pointer set on return to an implementation-owned array of booleans, where element i indicates whether the output key with numeric value i (see UmamiOutputKey) can be produced by this implementation.

  • count – pointer set on return to the number of elements in *supported. A caller built against a newer header should treat any key index beyond *count as not supported.

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