MO Integrals#

cuest.bindings.cuestDFMOIntegralsComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspaceDescriptor: int,
numCoefficientMatrices: int,
numLeftOrbitals: collections.abc.Sequence[int],
numRightOrbitals: collections.abc.Sequence[int],
leftCoefficientMatrices: cuest.bindings.cuest.Pointer,
rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
outTensors: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

This function determines the workspace required to perform an AO → MO transformation of the DF three-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 the corresponding DF MO integral compute routine.

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

Parameters#

handle[in]CuestHandle

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

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

parameters[in]cuestDFMOIntegralsComputeParameters_t

Compute parameters. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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 variableBufferSize does not limit total memory usage. The value of variableBufferSize must not change between WorkspaceQuery and Compute calls.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

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

numCoefficientMatrices[in]int

Number of pairs of coefficient matrices. Must be > 0.

numLeftOrbitals[in]list of int

Number of molecular orbitals for each left coefficient matrix (size: numCoefficientMatrices) on the CPU. Each entry must be > 0. Must not be NULL.

numRightOrbitals[in]list of int

Number of molecular orbitals for each right coefficient matrix (size: numCoefficientMatrices) on the CPU. Each entry must be > 0. Must not be NULL.

leftCoefficientMatricesPointer

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

rightCoefficientMatricesPointer

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

outTensorsPointer

Output concatenated MO integral tensors. Each tensor has shape (naux × numLeftOrbitals[i] × numRightOrbitals[i]) on the GPU. Total size: naux × sum(numRightOrbitals[i] × numLeftOrbitals[i]). May be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestDFMOIntegralsCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspace: int,
numCoefficientMatrices: int,
numLeftOrbitals: collections.abc.Sequence[int],
numRightOrbitals: collections.abc.Sequence[int],
leftCoefficientMatrices: cuest.bindings.cuest.Pointer,
rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
outTensors: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Transform the three-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.

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

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

Density fitting integral computation plan (opaque handle). Must not be NULL.

parameters[in]cuestDFMOIntegralsComputeParameters_t

Compute parameters. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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

temporaryWorkspace[in]Workspace

Temporary workspace buffers (preallocated using the query function). Must not be NULL.

numCoefficientMatrices[in]int

Number of pairs of coefficient matrices. Must be > 0.

numLeftOrbitals[in]list of int

Number of molecular orbitals for each left coefficient matrix (size: numCoefficientMatrices). Each entry must be > 0. Must not be NULL.

numRightOrbitals[in]list of int

Number of molecular orbitals for each right coefficient matrix (size: numCoefficientMatrices). Each entry must be > 0. Must not be NULL.

leftCoefficientMatrices[in]Pointer

Concatenated left coefficient matrices. Each matrix has shape (numLeftOrbitals[i] × nao). Total size: sum(numLeftOrbitals[i]) × nao. Must not be NULL.

rightCoefficientMatrices[in]Pointer

Concatenated right coefficient matrices. Each matrix has shape (numRightOrbitals[i] × nao). Total size: sum(numRightOrbitals[i]) × nao. Must not be NULL.

outTensors[out]Pointer

Output concatenated MO integral tensors. Each tensor has shape (naux × numLeftOrbitals[i] × numRightOrbitals[i]). Total size: naux × sum(numLeftOrbitals[i] × numRightOrbitals[i]). Must not be NULL.

Returns#

status[out]cuestStatus_t