Coulomb#

group Coulomb

Functions

cuestStatus_t cuestDFCoulombCompute(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFCoulombComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
const double *densityMatrix,
double *outCoulombMatrix
)#

Compute the AO Coulomb (J) matrix using density fitting (DF) with the supplied DF integral plan and density matrix.

This routine computes the Coulomb matrix (J) from a density matrix using an auxiliary basis and density-fitted integrals. The user must provide a preallocated density matrix (size: nao × nao), a cuestDFIntPlan_t, and a preallocated output buffer (size: nao × nao). All required temporary workspace must be allocated using the size returned by cuestDFCoulombComputeWorkspaceQuery.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] Density-fitted integral plan (opaque handle) constructed with cuestDFIntPlanCreate. Must not be NULL.

  • parameters – [in] Compute parameters (cuestDFCoulombComputeParameters_t). Must not be NULL

  • temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.

  • densityMatrix – [in] Input density matrix (size: nao × nao) on GPU. Must not be NULL.

  • outCoulombMatrix – [out] Output buffer for computed Coulomb matrix (size: nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_PLAN if the cuestDFIntPlan_t is not correctly configured or in a dirty state;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFCoulombComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFCoulombComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
double *outCoulombMatrix
)#

Query the temporary workspace required (in bytes) for a DF Coulomb matrix computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided cuestDFIntPlan_t. Only sizes are computed; output and density buffers may be NULL.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] Density-fitted integral plan (opaque handle). Must not be NULL.

  • parameters – [in] Compute parameters (cuestDFCoulombComputeParameters_t). Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.

  • densityMatrix – Optional density matrix (may be NULL).

  • outCoulombMatrix – Optional output Coulomb matrix (may be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_PLAN if the cuestDFIntPlan_t is not correctly configured or in a dirty state;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.