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} = \sum^{N_{ao}}_{\lambda\sigma} \sum^{N_{occ}}_{i} \left[ f_{\rm HF} (\mu\lambda|\frac{1}{r}|\nu\sigma) + f_{\rm LRC} (\mu\lambda|\frac{{\rm erf}(\omega r)}{r}|\nu\sigma) \right] C_{i\lambda} C_{i\sigma} \]

where \( f_{\rm HF} \) is the fraction of Hartree-Fock exchange to add (CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \( f_{\rm LRC} \) is the fraction of the long-range component of range-separated exchange to add (CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \( \omega \) is the range-separation parameter.

When the operator definition leads to zero exchange, the exchange matrix is still 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.

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 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 – Optional pointer to coefficient matrix buffer (may be NULL).

  • outExchangeMatrix – 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_PLAN if the cuestDFIntPlan_t is not correctly configured or in a dirty state;

  • CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFNonsymmetricExchangeCompute(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFNonsymmetricExchangeComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numCoefficientMatrices,
uint64_t numOccupied,
const double *leftCoefficientMatrix,
const double *rightCoefficientMatrices,
double *outExchangeMatrices
)#

Compute AO exchange (K) matrices with nonsymmetric densities using density fitting (DF) with the supplied DF integral plan and coefficient matrices.

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

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

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

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

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

Since

v0.2.0

The exchange matrix is computed as:

\[ K^{n}_{\mu\nu} = \sum^{N_{ao}}_{\lambda\sigma} \sum^{N_{occ}}_{i} \left[ f_{\rm HF} (\mu\lambda|\frac{1}{r}|\nu\sigma) + f_{\rm LRC} (\mu\lambda|\frac{{\rm erf}(\omega r)}{r}|\nu\sigma) \right] L_{i\lambda} R^{n}_{i\sigma} \]

where \( f_{\rm HF} \) is the fraction of Hartree-Fock exchange to add (CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \( f_{\rm LRC} \) is the fraction of the long-range component of range-separated exchange to add (CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \( \omega \) is the range-separation parameter.

When the operator definition leads to zero exchange, the exchange matrix is still 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 (cuestDFNonsymmetricExchangeComputeParameters_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.

  • numCoefficientMatrices – [in] Number of right coefficient matrices provided and output exchange matrices; must be greater than zero.

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

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

  • rightCoefficientMatrices – [in] Input right coefficient matrices (size: numCoefficientMatrices × numOccupied × nao) on GPU. Must not be NULL.

  • outExchangeMatrices – [out] Output buffer for the AO exchange matrices (size: numCoefficientMatrices × 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 numOccupied or numCoefficientMatrices is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFNonsymmetricExchangeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestDFIntPlan_t plan,
const cuestDFNonsymmetricExchangeComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numCoefficientMatrices,
uint64_t numOccupied,
const double *leftCoefficientMatrix,
const double *rightCoefficientMatrices,
double *outExchangeMatrices
)#

Query the temporary workspace required (in bytes) for the calculation of nonsymmetric DF exchange matrices.

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

Since

v0.2.0

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 (cuestDFNonsymmetricExchangeComputeParameters_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.

  • numCoefficientMatrices – [in] Number of right coefficient matrices provided and output exchange matrices; must be greater than zero.

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

  • leftCoefficientMatrix – Input left coefficient matrix (size: numOccupied × nao) on GPU. May be NULL.

  • rightCoefficientMatrices – Input right coefficient matrices (size: numCoefficientMatrices × numOccupied × nao) on GPU. May be NULL.

  • outExchangeMatrices – Output buffer for the AO exchange matrices (size: numCoefficientMatrices × nao × nao) on GPU. 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 numOccupied or numCoefficientMatrices is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.