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
cublasSetStreamorcusolverDnSetStreamwith the provided cudaStream);
- Parameters:
parameters – [in] Parameter structure handle (must not be NULL).
Create with
cuestParametersCreate()usingCUEST_HANDLE_PARAMETERS. Set attributes withcuestParametersConfigure().9 configurable attributes
CUEST_HANDLE_PARAMETERS_CUDASTREAMcudaStream_tCUDA stream handle. NULL value allocates a CUDA stream internally.
May be NULL.
Default:
NULLCUEST_HANDLE_PARAMETERS_CUBLAScublasHandle_tcuBLAS handle. NULL value allocates a cuBLAS handle internally.
May be NULL.
Default:
NULLCUEST_HANDLE_PARAMETERS_CUSOLVERcusolverDnHandle_tcuSolver handle. NULL value allocates a cuSolver handle internally.
May be NULL.
Default:
NULLCUEST_HANDLE_PARAMETERS_MAX_GAUSS_HERMITEuint64_tMaximum number of quadrature points.
Default:
20CUEST_HANDLE_PARAMETERS_MAX_L_SOLID_HARMONICuint64_tHighest angular momentum for solid harmonics.
Default:
10CUEST_HANDLE_PARAMETERS_MAX_RYSuint64_tMaximum number of Rys points. (0 specifies the largest available).
Default:
0CUEST_HANDLE_PARAMETERS_RYS_SCHEMEcuestHandleParametersRysScheme_tSpecifies which scheme should be used to build the Rys quadrature table.
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_tParallel 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_SUCCESSon success,CUEST_STATUS_NULL_POINTERifparametersorhandleis NULL,CUEST_STATUS_INVALID_TYPEifparametersis not of thecuestHandleParameters_ttype,CUEST_STATUS_UNSUPPORTED_ARCHITECTUREif the GPU architecture is not supported by cuEST,CUEST_STATUS_INVALID_ARGUMENTif a handle parameter value is invalid (e.g. an invalid JIT compile-thread count or an unsafe JIT cache directory),CUEST_STATUS_HOME_NOT_FOUNDif no JIT cache directory was specified and the HOME environment variable is unset or empty,CUEST_STATUS_EXCEPTIONif the JIT cache path exists but is not a directory or cannot be created,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
-
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_SUCCESSon success,CUEST_STATUS_NULL_POINTERif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_MODEcuEST will use algorithms that are determined heuristically to maximize performance. Some results may use mixed precision arithmetic.CUEST_NATIVE_FP64_MATH_MODEcuEST will use FP64 arithmetic everywhere.
- Parameters:
handle – [inout] Opaque cuEST handle (must not be NULL).
mode – [in] Math mode enum.
- Returns:
CUEST_STATUS_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_INVALID_ARGUMENTif thecuestMathMode_tis invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_NULL_POINTERif mode is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_NULL_POINTERif targetMajorVersion or targetMinorVersion is NULL,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_NULL_POINTERif majorVersion is NULL,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_NULL_POINTERif minorVersion is NULL,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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_SUCCESSon success,CUEST_STATUS_INVALID_HANDLEif handle is NULL,CUEST_STATUS_INVALID_TYPEif handle is not of thecuestHandle_ttype,CUEST_STATUS_NULL_POINTERif patchVersion is NULL,CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.