Exchange#

cuest.bindings.cuestDFSymmetricExchangeComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspaceDescriptor: int,
numOccupied: int,
coefficientMatrix: cuest.bindings.cuest.Pointer,
outExchangeMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

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

parameters[in]cuestDFSymmetricExchangeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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]WorkspaceDescriptor

Output descriptor for workspace sizes (host and device). Must not be NULL.

numOccupied[in]int

Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.

coefficientMatrixPointer

Optional pointer to coefficient matrix buffer. May be NULL.

outExchangeMatrixPointer

Optional pointer to output exchange matrix buffer. May be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestDFSymmetricExchangeCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspace: int,
numOccupied: int,
coefficientMatrix: cuest.bindings.cuest.Pointer,
outExchangeMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

This function computes the density-fitted AO exchange matrix from an orbital coefficient matrix and a DF plan.

  • The input coefficient matrix must be preallocated to size (numOccupied × nao). Data is expected to be in row-major format.

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

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

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

parameters[in]cuestDFSymmetricExchangeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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]Workspace

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

numOccupied[in]int

Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.

coefficientMatrix[in]Pointer

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

outExchangeMatrix[out]Pointer

Output buffer for the AO exchange 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.bindings.cuestDFNonsymmetricExchangeComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspaceDescriptor: int,
numCoefficientMatrices: int,
numOccupied: int,
leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
outExchangeMatrices: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

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]cuestDFNonsymmetricExchangeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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]WorkspaceDescriptor

Output descriptor for workspace sizes (host and device). Must not be NULL.

numCoefficientMatrices[in]: int

Number of right coefficient matrices provided and output exchange matrices; must be greater than zero.

numOccupied[in]int

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

leftCoefficientMatrixPointer

Optional pointer to the left coefficient matrix buffer. May be NULL.

rightCoefficientMatricesPointer

Optional pointer to right coefficient matrices buffer. May be NULL.

outExchangeMatricesPointer

Optional pointer to output exchange matrix buffer. May be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestDFNonsymmetricExchangeCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspace: int,
numCoefficientMatrices: int,
numOccupied: int,
leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
outExchangeMatrices: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

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

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

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

parameters[in]cuestDFNonsymmetricExchangeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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]Workspace

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

numCoefficientMatrices[in]int

Number of right coefficient matrices provided and output exchange matrices; must be greater than zero.

numOccupied[in]int

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

leftCoefficientMatrix[in]Pointer

Input left coefficient matrix (size: numOccupied × nao) on GPU. Must not be NULL.

rightCoefficientMatrices[in]Pointer

Input right coefficient matrices (size: numCoefficientMatrices × numOccupied × nao) on GPU. Must not be NULL.

outExchangeMatrices[out]Pointer

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#

status[out]cuestStatus_t