Context#

group Context

Functions

cuestStatus_t cuestCreate(
cuestHandleParameters_t parameters,
cuestHandle_t *handle
)#

Creates a new cuEST handle and its associated resources from a parameter structure.

Ownership of handles or pointers passed into the structure is NOT transferred. Default parameters will construct a generic GPU context.

Requirements:

  • A cudaStream alone may be provided, all others may be left NULL.

  • If cuBLAS or cuSolver handles are specified, a cudaStream must also be specified.

  • When cuBLAS or cuSolver handles are specified, these handles must be set to operate on the provided cudaStream. (i.e. by calling cublasSetStream or cusolverDnSetStream with the provided cudaStream);

Parameters:
  • parameters – [in] Parameter structure handle (must not be NULL).

    Create with cuestParametersCreate() using CUEST_HANDLE_PARAMETERS. Set attributes with cuestParametersConfigure().

    9 configurable attributes
    CUEST_HANDLE_PARAMETERS_CUDASTREAMcudaStream_t

    CUDA stream handle. NULL value allocates a CUDA stream internally.

    May be NULL.

    Default: NULL

    CUEST_HANDLE_PARAMETERS_CUBLAScublasHandle_t

    cuBLAS handle. NULL value allocates a cuBLAS handle internally.

    May be NULL.

    Default: NULL

    CUEST_HANDLE_PARAMETERS_CUSOLVERcusolverDnHandle_t

    cuSolver handle. NULL value allocates a cuSolver handle internally.

    May be NULL.

    Default: NULL

    CUEST_HANDLE_PARAMETERS_MAX_GAUSS_HERMITEuint64_t

    Maximum number of quadrature points.

    Default: 20

    CUEST_HANDLE_PARAMETERS_MAX_L_SOLID_HARMONICuint64_t

    Highest angular momentum for solid harmonics.

    Default: 10

    CUEST_HANDLE_PARAMETERS_MAX_RYSuint64_t

    Maximum number of Rys points. (0 specifies the largest available).

    Default: 0

    CUEST_HANDLE_PARAMETERS_RYS_SCHEMEcuestHandleParametersRysScheme_t

    Specifies which scheme should be used to build the Rys quadrature table.

    Default: CUEST_HANDLE_PARAMETERS_RYS_SCHEME_06_21_2025

    CUEST_HANDLE_PARAMETERS_JIT_CACHE_DIRconst char*

    JIT kernel cache directory. Empty string uses the derived default (~/.cuest_cache/cuest-cuda<N>-v<version>/). Must be a trusted, per-user, non-world-writable path (see security notes). The directory is created at cuestCreate if it does not exist. An existing directory that is a symlink, or world-writable without the sticky bit, is rejected at cuestCreate with CUEST_STATUS_INVALID_ARGUMENT; a path that exists but is not a directory, or that cannot be created, fails cuestCreate with CUEST_STATUS_EXCEPTION; an existing directory that is not writable is accepted at cuestCreate and fails at the first JIT compilation.

    NUL-terminated; the value returned by a query is allocated with malloc and must be freed by the caller with C's native free(). The allocation only occurs when the query completes successfully (CUEST_STATUS_SUCCESS); on error nothing is allocated to free.

    Default: "" (derived default)

    CUEST_HANDLE_PARAMETERS_JIT_COMPILE_THREADSint32_t

    Parallel JIT precompile worker threads. Must be >= 1 (a smaller value is rejected at cuestCreate with CUEST_STATUS_INVALID_ARGUMENT); clamped to an internal upper bound of 256.

    Default: 16

  • handle – [out] Pointer to opaque cuEST handle for output.

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_NULL_POINTER if parameters or handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if parameters is not of the cuestHandleParameters_t type,

  • CUEST_STATUS_UNSUPPORTED_ARCHITECTURE if the GPU architecture is not supported by cuEST,

  • CUEST_STATUS_INVALID_ARGUMENT if a handle parameter value is invalid (e.g. an invalid JIT compile-thread count or an unsafe JIT cache directory),

  • CUEST_STATUS_HOME_NOT_FOUND if no JIT cache directory was specified and the HOME environment variable is unset or empty,

  • CUEST_STATUS_EXCEPTION if the JIT cache path exists but is not a directory or cannot be created,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDestroy(cuestHandle_t handle)#

Destroys a cuEST handle and all associated resources.

Frees memory for GPU resources, quadrature data, solid harmonics coefficients, and rys table.

Parameters:

handle – [in] Opaque cuEST handle to destroy (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_NULL_POINTER if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestSetMathMode(
cuestHandle_t handle,
cuestMathMode_t mode
)#

Sets the math mode used when cuEST functions are called with this handle.

  • CUEST_DEFAULT_MATH_MODE cuEST will use algorithms that are determined heuristically to maximize performance. Some results may use mixed precision arithmetic.

  • CUEST_NATIVE_FP64_MATH_MODE cuEST will use FP64 arithmetic everywhere.

Parameters:
  • handle – [inout] Opaque cuEST handle (must not be NULL).

  • mode – [in] Math mode enum.

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_INVALID_ARGUMENT if the cuestMathMode_t is invalid;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestGetMathMode(
cuestHandle_t handle,
cuestMathMode_t *mode
)#

Gets the math mode associated with this handle.

Parameters:
  • handle – [in] Opaque cuEST handle (must not be NULL).

  • mode – [out] Math mode enum (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_NULL_POINTER if mode is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestSetComputeCapabilityTarget(
cuestHandle_t handle,
uint32_t targetMajorVersion,
uint32_t targetMinorVersion
)#

Sets the compute capability used in heuristics to determine the most performant code path.

Notes:

  • Manually setting the compute capability target is not recommended for production calculations. This option is intended only to compare numerical performance of the same algorithm on different architectures.

  • Not all algorithms may be available on all architectures. Changing the compute capability target may result in exceptions during subsequent calls to cuEST.

  • The compute capability target only affects heuristics. It does not affect kernel execution or JIT compilation.

Parameters:
  • handle – [inout] Opaque cuEST handle (must not be NULL).

  • targetMajorVersion – [in] Compute capability target major version.

  • targetMinorVersion – [in] Compute capability target minor version.

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestGetComputeCapabilityTarget(
cuestHandle_t handle,
uint32_t *targetMajorVersion,
uint32_t *targetMinorVersion
)#

Gets the compute capability used in heuristics to determine the most performant code path.

Parameters:
  • handle – [in] Opaque cuEST handle (must not be NULL).

  • targetMajorVersion – [out] Compute capability target major version (must not be NULL).

  • targetMinorVersion – [out] Compute capability target minor version (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_NULL_POINTER if targetMajorVersion or targetMinorVersion is NULL,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestGetMajorVersion(
cuestHandle_t handle,
uint32_t *majorVersion
)#

Gets the major version of the cuEST library.

Parameters:
  • handle – [in] Opaque cuEST handle (must not be NULL).

  • majorVersion – [out] Major version of the cuEST library (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_NULL_POINTER if majorVersion is NULL,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestGetMinorVersion(
cuestHandle_t handle,
uint32_t *minorVersion
)#

Gets the minor version of the cuEST library.

Parameters:
  • handle – [in] Opaque cuEST handle (must not be NULL).

  • minorVersion – [out] Minor version of the cuEST library (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_NULL_POINTER if minorVersion is NULL,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestGetPatchVersion(
cuestHandle_t handle,
uint32_t *patchVersion
)#

Gets the patch version of the cuEST library.

Parameters:
  • handle – [in] Opaque cuEST handle (must not be NULL).

  • patchVersion – [out] Patch version of the cuEST library (must not be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success,

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL,

  • CUEST_STATUS_INVALID_TYPE if handle is not of the cuestHandle_t type,

  • CUEST_STATUS_NULL_POINTER if patchVersion is NULL,

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.