Exchange#

group Exchange

Functions

cuestStatus_t cuestDFSymmetricExchangeCompute(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFSymmetricExchangeComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numOccupied,
const double *coefficientMatrix,
double *outExchangeMatrix
)#

Compute the AO symmetric exchange (K) matrix using density fitting (DF) with the supplied DF integral plan and coefficient matrix.

  • The input coefficient matrix must be preallocated to size (numOccupied × nao) (row-major).

  • The output buffer outExchangeMatrix must be preallocated for (nao × nao) doubles.

  • All handles, pointers, and buffers must be valid and non-NULL.

  • Temporary workspace must be preallocated using size returned by cuestDFSymmetricExchangeComputeWorkspaceQuery.

The exchange matrix is computed as:

\[ K_{\mu\nu} = {\rm f_E} \sum^{N_{ao}}_{\lambda\sigma} \sum^{N_{occ}}_{i} (\mu\lambda|\nu\sigma) C_{i\lambda} C_{i\sigma} \]

where \( f_E \) is the fraction of Hartree-Fock exchange to add, CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION.

When CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION == 0.0, the exchange matrix is calculated and scaled by zero. The user should avoid calling this function in that case to avoid unnecessary compute.

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 (cuestDFSymmetricExchangeComputeParameters_t). Must not be NULL

  • variableBufferSize – [in] User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. For most problem sizes, 8 GB is a good buffer size. On older devices, such as A100, smaller buffer sizes down to 2 GB can be used without degrading performance. Host memory is currently unused. Note that the variableBufferSize does not limit total memory usage. There may be static allocations required outside of the scope of what is limited by the variableBufferSize. This value must remain unchanged between WorkspaceQuery and Compute calls.

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

  • numOccupied – [in] Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.

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

  • outExchangeMatrix – [out] Output buffer for the AO exchange matrix (size: nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results. The result is scaled by CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION as provided in the cuestDFIntPlan_t.

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_ARGUMENT if numOccupied is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFSymmetricExchangeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFSymmetricExchangeComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numOccupied,
const double *coefficientMatrix,
double *outExchangeMatrix
)#

Query the temporary workspace required (in bytes) for a DF exchange matrix calculation.

This function returns (via output parameters) the host and device workspace buffer sizes needed to perform a symmetric exchange computation, given the plan and matrix dimensions. The coefficient matrix and output buffer may be NULL (only sizes are computed).

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 (cuestDFSymmetricExchangeComputeParameters_t). Must not be NULL

  • variableBufferSize – [in] User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. For most problem sizes, 8 GB is a good buffer size. On older devices, such as A100, smaller buffer sizes down to 2 GB can be used without degrading performance. Host memory is currently unused. Note that the variableBufferSize does not limit total memory usage. There may be static allocations required outside of the scope of what is limited by the variableBufferSize. This value must remain unchanged between WorkspaceQuery and Compute calls.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes (host and device). Must not be NULL.

  • numOccupied – [in] Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.

  • coefficientMatrix – [in] Optional pointer to coefficient matrix buffer (may be NULL).

  • outExchangeMatrix – [in] Optional pointer to output exchange matrix buffer (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_ARGUMENT if numOccupied is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.