Coulomb

cuest.bindings.cuestDFCoulombComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestDFIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

densityMatrix: cuest.bindings.cuest.Pointer,

outCoulombMatrix: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

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 plan. 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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestDFIntPlanHandle

Density-fitted integral plan (opaque handle). Must not be NULL.

parameters[in]cuestDFCoulombComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place.

densityMatrixPointer

Optional density matrix. May be NULL.

outCoulombMatrixPointer

Optional output Coulomb matrix. May be NULL.

Returns

status[out]cuestStatus_t

• 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.

cuest.bindings.cuestDFCoulombCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestDFIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

densityMatrix: cuest.bindings.cuest.Pointer,

outCoulombMatrix: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

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) 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]CuestHandle

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

Density-fitted integral plan (opaque handle) constructed with cuestDFIntPlanCreate(). Must not be NULL.

parameters[in]cuestDFCoulombComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffer for this operation. Must not be NULL.

densityMatrix[in]Pointer

Input density matrix (size: nao × nao) on the GPU. Must not be NULL.

outCoulombMatrix[out]Pointer

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

Returns

status[out]cuestStatus_t

• 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.