MO Integrals#

group DFMOIntegrals

Functions

cuestStatus_t cuestDFMOIntegralsCompute(
cuestHandle_t handle,
cuestDFIntPlan_t plan,
const cuestDFMOIntegralsComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numCoefficientMatrices,
const uint64_t *numLeftOrbitals,
const uint64_t *numRightOrbitals,
const double *leftCoefficientMatrices,
const double *rightCoefficientMatrices,
double *outTensors
)#

Transforms the 3-index density fitting tensor from the AO basis to the MO basis.

This routine transforms three-index AO integrals into the MO basis within the density fitting representation. Pairs of coefficient matrices are taken as input.

Since

v0.2.0

Starting from a density-fitted representation of the AO integrals:

\[\left[ f_{\rm HF} (\mu\nu|\frac{1}{r}|\lambda\sigma) + f_{\rm LRC} (\mu\nu|\frac{{\rm erf}(\omega r)}{r}|\lambda\sigma) \right] = \sum_{A} B^{A}_{\mu\nu} B^{A}_{\lambda\sigma} \]

This function performs the transformation:

\[ B^{A}_{ia} = \sum_{\mu\nu} B^{A}_{\mu\nu} C(L)_{i\mu} C(R)_{a\nu} \]

The resulting tensors can be used to directly construct 4-index MO integrals by contracting over the auxiliary index.

\[\left[ f_{\rm HF} (ia|\frac{1}{r}|jb) + f_{\rm LRC} (ia|\frac{{\rm erf}(\omega r)}{r}|jb) \right] = \sum_{A} B^{A}_{ia} B^{A}_{jb} \]

The transformation is most efficient when the MO dimension of C(L) is smaller than the MO dimension of C(R), as C(L) is applied first. The resulting tensor is transformed by the fitting metric.

Multiple MO integral tensors can be evaluated in a single function call. The resulting MO integral tensors respect the values of CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION, CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION, and CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA set in the cuestDFIntPlan_t.

This function supports the use of a cuestDFIntPlan_t constructed with the CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT parameter set to either 0 or 1.

All required temporary workspace must be sized using the corresponding workspace query function. A variableBufferSize descriptor must also be provided to constrain the memory usage.

Parameters:

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

  • plan – [in] DF integral computation plan (opaque handle). Must not be NULL.

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

  • variableBufferSize – [in] The variableBufferSize determines the size of an internal scratch buffer used for certain transformations. A buffer of 2GB is a reasonable default value. Host memory is currently unused. Note that the variableBufferSize does not limit total memory usage. The value of the variableBufferSize must not change between WorkspaceQuery and Compute calls.

  • temporaryWorkspace – [in] Temporary workspace buffers (preallocated for this operation using the query function). Must not be NULL.

  • numCoefficientMatrices – [in] Number of pairs of coefficient matrices. Must be > 0.

  • numLeftOrbitals – [in] Array of molecular orbital counts for each left coefficient matrix (size: numCoefficientMatrices) on CPU. Each entry must be > 0. Must not be NULL.

  • numRightOrbitals – [in] Array of molecular orbital counts for each right coefficient matrix (size: numCoefficientMatrices) on CPU. Each entry must be > 0. Must not be NULL.

  • leftCoefficientMatrices – [in] Concatenated left coefficient matrices. Each matrix has shape [numLeftOrbitals[i], nao] on GPU. Total size: sum(numLeftOrbitals[i]) × nao. Must not be NULL.

  • rightCoefficientMatrices – [in] Concatenated right coefficient matrices. Each matrix has shape [numRightOrbitals[i], nao] on GPU. Total size: sum(numRightOrbitals[i]) × nao. Must not be NULL.

  • outTensors – [out] Output concatenated MO integral tensors. Each tensor has shape [naux, numLeftOrbitals[i], numRightOrbitals[i]] on GPU. Total size: naux × sum(numRightOrbitals[i] × numLeftOrbitals[i]). Must not 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 numCoefficientMatrices == 0, or any numLeftOrbitals[i] == 0, or any numRightOrbitals[i] == 0;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFMOIntegralsComputeWorkspaceQuery(
cuestHandle_t handle,
cuestDFIntPlan_t plan,
const cuestDFMOIntegralsComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numCoefficientMatrices,
const uint64_t *numLeftOrbitals,
const uint64_t *numRightOrbitals,
const double *leftCoefficientMatrices,
const double *rightCoefficientMatrices,
double *outTensors
)#

Query the temporary workspace required to transform the 3-index density fitting tensor from the AO basis to the MO basis.

This function determines the workspace required to perform an AO to MO transform of the DF 3-index tensor with the given plan, coefficient matrices, and maximum workspace constraint. The output descriptor is filled on success and can be used to allocate host and device workspace buffers prior to calling cuestDFMOIntegralsCompute.

Since

v0.2.0

Some input pointers (coefficientMatrices and outTensors) are optional and may be NULL.

Parameters:

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

  • plan – [in] DF integral computation plan (opaque handle). Must not be NULL.

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

  • variableBufferSize – [in] The variableBufferSize determines the size of an internal scratch buffer used for certain transformations. A buffer of 2GB is a reasonable default value. Host memory is currently unused. Note that the variableBufferSize does not limit total memory usage. The value of the variableBufferSize must not change between WorkspaceQuery and Compute calls.

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

  • numCoefficientMatrices – [in] Number of pairs of coefficient matrices. Must be > 0.

  • numLeftOrbitals – [in] Array of molecular orbital counts for each left coefficient matrix (size: numCoefficientMatrices) on CPU. Each entry must be > 0. Must not be NULL.

  • numRightOrbitals – [in] Array of molecular orbital counts for each right coefficient matrix (size: numCoefficientMatrices) on CPU. Each entry must be > 0. Must not be NULL.

  • leftCoefficientMatrices – Concatenated left coefficient matrices. Each matrix has shape [numLeftOrbitals[i], nao] on GPU. Total size: sum(numLeftOrbitals[i]) × nao. May be NULL.

  • rightCoefficientMatrices – Concatenated right coefficient matrices. Each matrix has shape [numRightOrbitals[i], nao] on GPU. Total size: sum(numRightOrbitals[i]) × nao. May be NULL.

  • outTensors – Output concatenated MO integral tensors. Each tensor has shape [naux, numLeftOrbitals[i], numRightOrbitals[i]] on GPU. Total size: naux × sum(numRightOrbitals[i] × numLeftOrbitals[i]). 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 numCoefficientMatrices == 0, or any numLeftOrbitals[i] == 0, or any numRightOrbitals[i] == 0;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.