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,
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) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for workspace sizes (host and device). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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
outExchangeMatrixmust 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().A range-separated plan must have been created with
CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULL(the default); aCUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_NONEplan returnsCUEST_STATUS_INVALID_PLAN.
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) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFNonsymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for workspace sizes (host and device). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedornumCoefficientMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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
outExchangeMatricesmust 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().A range-separated plan must have been created with
CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULL(the default); aCUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_NONEplan returnsCUEST_STATUS_INVALID_PLAN.
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) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFNonsymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedornumCoefficientMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKSymmetricExchangeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Compute AO symmetric exchange (K) matrices using grid-based exchange (Grid-K) with the supplied Grid-K integral plan and symmetric density matrices.
The Grid-K exchange matrix is computed by quadrature on the plan’s molecular grid as
\[\tilde{K}^{i}_{pq} = \sum_{Ars} w^{A} \, X_{p}^{A} \, X_{r}^{A} \, V_{qs}^{A} \, D^{i}_{rs}\]where \(X_{p}^{A} = \phi_{p}(\mathbf{r}_{A})\) is the collocation of AO \(p\) at grid point \(A\), \(w^{A}\) is the Becke quadrature weight of that point, and \(V_{qs}^{A}\) is the AO pair potential evaluated at that point,
\[V_{qs}^{A} = \int \phi_{q}(\mathbf{r}) \left[ f_{\rm HF} \frac{1}{|\mathbf{r} - \mathbf{r}_{A}|} + f_{\rm LRC} \frac{{\rm erf}(\omega |\mathbf{r} - \mathbf{r}_{A}|)}{|\mathbf{r} - \mathbf{r}_{A}|} \right] \phi_{s}(\mathbf{r}) \, d\mathbf{r}\]where \(f_{\rm HF}\) is the fraction of Hartree-Fock exchange to add (
CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \(f_{\rm LRC}\) is the fraction of the long-range component of range-separated exchange to add (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \(\omega\) is the range-separation parameter (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA). The operator and the collocation threshold are those fixed when thecuestGridKIntPlan_twas created. For a plan created withCUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRIC, the collocation \(X\) is replaced by the fitted collocation \(\bar{X} = M X\) (seecuestGridKIntPlanCreate()).The grid-based electron repulsion operator does not obey \((pq|rs) = (rs|pq)\), so \(\tilde{K}^{i}\) above is not operator-symmetric. Operator symmetry is restored before the result is returned:
\[K^{i} = \frac{1}{2} \left( \tilde{K}^{i} + \left( \tilde{K}^{i} \right)^{T} \right)\]Each input density matrix \(D^{i}\) MUST be symmetric (for example \(D = C^{T} C\), formed from the occupied orbital coefficients). This is not checked. This function recovers the exact operator-symmetric exchange only for a symmetric density. Use
cuestGridKNonsymmetricExchangeCompute()for general (non-symmetric) densities.When the operator definition leads to zero exchange, the exchange matrices are still calculated and scaled by zero. The user should avoid calling this function in that case to avoid unnecessary compute.
The input density matrices must be preallocated to size (
numDensityMatrices× nao × nao) (row-major), stacked contiguously, where nao is the number of atomic orbitals of the plan’s primary basis.The output buffer
outExchangeMatricesmust be preallocated for (numDensityMatrices× nao × nao) doubles.All handles, pointers, and buffers must be valid and non-NULL.
Temporary workspace must be preallocated using the size returned by
cuestGridKSymmetricExchangeComputeWorkspaceQuery()for the samevariableBufferSize.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and exchange matrices produced; must be greater than zero.
- densityMatrices[in]Pointer
Input stacked symmetric density matrices (size:
numDensityMatrices× nao × nao) on the GPU. Must not be NULL.- outExchangeMatrices[out]Pointer
Output buffer for the AO exchange matrices (size:
numDensityMatrices× nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results; block \(i\) receives the symmetric \(K^{i}\).
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKSymmetricExchangeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a symmetric Grid-K exchange matrix calculation.
This function returns (via output parameters) the host and device workspace buffer sizes needed to perform a symmetric Grid-K exchange computation, given the plan and matrix dimensions. The computation is simulated: no device memory is touched, only sizes are computed, and the density and output buffers may be NULL.
variableBufferSizeandnumDensityMatricesmust match the values passed to the subsequentcuestGridKSymmetricExchangeCompute()call.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for workspace sizes (host and device). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and exchange matrices produced; must be greater than zero.
- densityMatrices[in]Pointer
Optional pointer to the stacked density matrix buffer. May be NULL.
- outExchangeMatricesPointer
Optional pointer to the stacked output buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKNonsymmetricExchangeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Compute AO exchange (K) matrices with nonsymmetric densities using grid-based exchange (Grid-K) with the supplied Grid-K integral plan and density matrices.
The Grid-K exchange matrix is computed by quadrature on the plan’s molecular grid as
\[\tilde{K}^{i}_{pq} = \sum_{Ars} w^{A} \, X_{p}^{A} \, X_{r}^{A} \, V_{qs}^{A} \, D^{i}_{rs}\]where \(X_{p}^{A} = \phi_{p}(\mathbf{r}_{A})\) is the collocation of AO \(p\) at grid point \(A\), \(w^{A}\) is the Becke quadrature weight of that point, and \(V_{qs}^{A}\) is the AO pair potential evaluated at that point,
\[V_{qs}^{A} = \int \phi_{q}(\mathbf{r}) \left[ f_{\rm HF} \frac{1}{|\mathbf{r} - \mathbf{r}_{A}|} + f_{\rm LRC} \frac{{\rm erf}(\omega |\mathbf{r} - \mathbf{r}_{A}|)}{|\mathbf{r} - \mathbf{r}_{A}|} \right] \phi_{s}(\mathbf{r}) \, d\mathbf{r}\]where \(f_{\rm HF}\) is the fraction of Hartree-Fock exchange to add (
CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \(f_{\rm LRC}\) is the fraction of the long-range component of range-separated exchange to add (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \(\omega\) is the range-separation parameter (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA). The operator and the collocation threshold are those fixed when thecuestGridKIntPlan_twas created. For a plan created withCUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRIC, the collocation \(X\) is replaced by the fitted collocation \(\bar{X} = M X\) (seecuestGridKIntPlanCreate()).The grid-based electron repulsion operator does not obey \((pq|rs) = (rs|pq)\). For a general density, operator symmetry is restored by symmetrizing the two orderings. Writing \(\bar{K}^{i}\) for the same build taken over the transposed density,
\[\bar{K}^{i}_{pq} = \sum_{Ars} w^{A} \, X_{p}^{A} \, X_{r}^{A} \, V_{qs}^{A} \, D^{i}_{sr}\]the returned matrix is
\[K^{i} = \frac{1}{2} \left( \tilde{K}^{i} + \left( \bar{K}^{i} \right)^{T} \right)\]The input density matrices \(D^{i}\) are general and need not be symmetric. This requires two Grid-K builds per density matrix, so it is roughly twice the cost of
cuestGridKSymmetricExchangeCompute().When the operator definition leads to zero exchange, the exchange matrices are still calculated and scaled by zero. The user should avoid calling this function in that case to avoid unnecessary compute.
The input density matrices must be preallocated to size (
numDensityMatrices× nao × nao) (row-major), stacked contiguously, where nao is the number of atomic orbitals of the plan’s primary basis.The output buffer
outExchangeMatricesmust be preallocated for (numDensityMatrices× nao × nao) doubles.All handles, pointers, and buffers must be valid and non-NULL.
Temporary workspace must be preallocated using the size returned by
cuestGridKNonsymmetricExchangeComputeWorkspaceQuery()for the samevariableBufferSize.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKNonsymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and exchange matrices produced; must be greater than zero.
- densityMatrices[in]Pointer
Input stacked density matrices (size:
numDensityMatrices× nao × nao) on the GPU. Must not be NULL.- outExchangeMatrices[out]Pointer
Output buffer for the AO exchange matrices (size:
numDensityMatrices× nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results; block \(i\) receives the operator-symmetrized \(K^{i}\).
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKNonsymmetricExchangeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a nonsymmetric Grid-K exchange matrix calculation.
This function returns (via output parameters) the host and device workspace buffer sizes needed to perform a nonsymmetric Grid-K exchange computation, given the plan and matrix dimensions. The computation is simulated: no device memory is touched, only sizes are computed, and the density and output buffers may be NULL.
variableBufferSizeandnumDensityMatricesmust match the values passed to the subsequentcuestGridKNonsymmetricExchangeCompute()call.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKNonsymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for workspace sizes (host and device). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and exchange matrices produced; must be greater than zero.
- densityMatrices[in]Pointer
Optional pointer to the stacked density matrix buffer. May be NULL.
- outExchangeMatrices[in]Pointer
Optional pointer to the stacked output buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKSymmetricExchangeDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outGradients: cuest.bindings.cuest.Pointer,
Compute nuclear gradients of the symmetric grid-based exchange (Grid-K) energy with the supplied Grid-K integral plan and symmetric density matrices.
The Grid-K exchange matrix and its exchange energy are computed by quadrature on the plan’s molecular grid as
\[\tilde{K}^{i}_{pq} = \sum_{Ars} w^{A} \, X_{p}^{A} \, X_{r}^{A} \, V_{qs}^{A} \, D^{i}_{rs}, \qquad E_{K}^{i} = \sum_{pq} D^{i}_{pq} \, \tilde{K}^{i}_{pq}\]where \(X_{p}^{A} = \phi_{p}(\mathbf{r}_{A})\) is the collocation of AO \(p\) at grid point \(A\), \(w^{A}\) is the Becke quadrature weight of that point, and \(V_{qs}^{A}\) is the AO pair potential evaluated at that point,
\[V_{qs}^{A} = \int \phi_{q}(\mathbf{r}) \left[ f_{\rm HF} \frac{1}{|\mathbf{r} - \mathbf{r}_{A}|} + f_{\rm LRC} \frac{{\rm erf}(\omega |\mathbf{r} - \mathbf{r}_{A}|)}{|\mathbf{r} - \mathbf{r}_{A}|} \right] \phi_{s}(\mathbf{r}) \, d\mathbf{r}\]where \(f_{\rm HF}\) is the fraction of Hartree-Fock exchange to add (
CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \(f_{\rm LRC}\) is the fraction of the long-range component of range-separated exchange to add (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \(\omega\) is the range-separation parameter (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA). The operator and the collocation threshold are those fixed when thecuestGridKIntPlan_twas created. For a plan created withCUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRIC, the collocation \(X\) is replaced by the fitted collocation \(\bar{X} = M X\) (seecuestGridKIntPlanCreate()). The gradients are consistent with the use of \(\bar{X}\), including the geometry dependence of \(M\).This function computes the nuclear gradient of that energy at fixed density,
\[\frac{\partial E_{K}^{i}}{\partial \mathbf{R}_{a}}, \qquad a = 1 \ldots \mathrm{numAtoms}\]including the Becke quadrature weight, AO collocation and pair-potential contributions. Grid points are treated as moving with their parent atoms, and grid-point derivatives are folded onto the owning atoms. The density is held fixed, so the result does not include the orbital-response (Pulay) terms of a full SCF gradient; those are the caller’s responsibility.
Each input density matrix \(D^{i}\) MUST be symmetric (for example \(D = C^{T} C\), formed from the occupied orbital coefficients). This is not checked. This function recovers the exact gradient of the operator-symmetric Grid-K exchange energy only for a symmetric density.
When the operator definition leads to zero exchange, the gradients are still calculated and scaled by zero. The user should avoid calling this function in that case to avoid unnecessary compute.
The input density matrices must be preallocated to size (
numDensityMatrices× nao × nao) (row-major), stacked contiguously, where nao is the number of atomic orbitals of the plan’s primary basis.The output buffer
outGradientsmust be preallocated for (numDensityMatrices× numAtoms × 3) doubles (row-major), where numAtoms is the number of atoms of the plan’s primary basis.All handles, pointers, and buffers must be valid and non-NULL.
Temporary workspace must be preallocated using the size returned by
cuestGridKSymmetricExchangeDerivativeComputeWorkspaceQuery()for the samevariableBufferSize.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and gradients produced; must be greater than zero.
- densityMatrices[in]Pointer
Input stacked symmetric density matrices (size:
numDensityMatrices× nao × nao) on the GPU. Must not be NULL.- outGradients[out]Pointer
Output buffer for the nuclear gradients (size:
numDensityMatrices× numAtoms × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results; block \(i\) receives the gradient for \(D^{i}\). Any prior contents are discarded, so the caller must accumulate into a running total explicitly.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKSymmetricExchangeDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outGradients: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a symmetric Grid-K exchange gradient calculation.
This function returns (via output parameters) the host and device workspace buffer sizes needed to perform a symmetric Grid-K exchange gradient computation, given the plan and matrix dimensions. The computation is simulated: no device memory is touched, only sizes are computed, and the density and output buffers may be NULL.
variableBufferSizeandnumDensityMatricesmust match the values passed to the subsequentcuestGridKSymmetricExchangeDerivativeCompute()call.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestGridKIntPlanHandle
Grid-K integral plan (opaque handle) constructed with
cuestGridKIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestGridKSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_GRIDKSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. 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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for workspace sizes (host and device). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices provided and gradients produced; must be greater than zero.
- densityMatrices[in]Pointer
Optional pointer to the stacked density matrix buffer. May be NULL.
- outGradientsPointer
Optional pointer to the stacked output buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif the grid or overlap integral plan used to create thecuestGridKIntPlan_thas been destroyed;CUEST_STATUS_INVALID_ARGUMENTifnumDensityMatricesis zero;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a direct 4-center exchange (K) matrix computation.
This function returns the workspace needed (host/device) for a single
cuestDirectSymmetricExchangeCompute()call, based on the provided plan. Only sizes are computed; the density and output buffers may be NULL.Compute parameters. The compilation mode and the integral screening are selected through the compute parameters:
CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD(double): Cauchy-Schwarz screening threshold (>= 0, density-weighted); contributions bounded below the threshold are skipped. A value of 0 disables screening. A negative value returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatricesPointer
Optional density matrices. May be NULL.
- outExchangeMatricesPointer
Optional output exchange matrices. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid (negative Schwarz threshold), ifCUEST_JIT_USAGE_MODE_ONis requested with the cuEST CUDA 12 package, or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeMatrices: cuest.bindings.cuest.Pointer,
Compute AO exchange (K) matrices directly from 4-center integrals for a batch of symmetric density matrices, with the supplied direct J/K plan.
This routine computes, for each density matrix \(m\) in the batch, the exchange matrix
\[K^{(m)}_{pr} = \sum_{qs} (pq|rs) D^{(m)}_{qs}\]exactly (no density fitting), integral-direct from the primary basis. Every density matrix in the batch is required to be symmetric (a nonsymmetric density gives undefined results). The user must provide
numDensityMatrices(>= 1) preallocated density matrices stored contiguously (size: numDensityMatrices × nao × nao, each symmetric) and a preallocated output buffer laid out the same way (size: numDensityMatrices × nao × nao). All required temporary workspace must be allocated using the size returned bycuestDirectSymmetricExchangeComputeWorkspaceQuery().This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Exchange operator. The operator is owned by the plan (the same convention as the density-fitted exchange plans):
\[K = f_{\rm HF}\,K_{1/r} + f_{\rm LRC}\,K_{{\rm erf}(\omega r)/r}\]where \(f_{\rm HF}\) is the fraction of full-range exchange (
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \(f_{\rm LRC}\) is the fraction of long-range range-separated exchange (CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \(\omega\) is the range-separation parameter (CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA), all set throughcuestDirectIntPlanParametersAttributes_tat plan creation.Compute parameters. The compilation mode and the integral screening are selected through the compute parameters:
CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD(double): Cauchy-Schwarz screening threshold (>= 0, density-weighted); contributions bounded below the threshold are skipped. A value of 0 disables screening. A negative value returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle; carries the exchange operator) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatrices[in]Pointer
Input density matrices (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on the GPU. Must not be NULL.
- outExchangeMatrices[out]Pointer
Output buffer for the computed exchange matrices (size: numDensityMatrices × nao × nao, contiguous) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid (negative Schwarz threshold), ifCUEST_JIT_USAGE_MODE_ONis requested with the cuEST CUDA 12 package, or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeGradients: cuest.bindings.cuest.Pointer,
Query the temporary workspace required for a direct 4-center exchange (K) energy gradient computation.
Fills the descriptor with the required temporary sizes for a single
cuestDirectSymmetricExchangeDerivativeCompute()call.densityMatricesandoutExchangeGradientsmay be NULL (never dereferenced).Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle; carries the exchange operator) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatricesPointer
Optional density matrices. May be NULL.
- outExchangeGradientsPointer
Optional output gradient buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERiftemporaryWorkspaceDescriptoror any other required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outExchangeGradients: cuest.bindings.cuest.Pointer,
Compute the nuclear gradients of the exchange energies at fixed density coefficients for a batch of symmetric density matrices, directly from 4-center integral derivatives.
For each density matrix \(m\) in the batch this routine computes
\[\nabla_A E_K^{(m)}, \qquad E_K^{(m)} = \sum_{pqrs} D^{(m)}_{pq} (pr|qs) D^{(m)}_{rs} = \sum_{pr} D^{(m)}_{pr} K^{(m)}_{pr}\]as a pure integral-derivative contraction with the plan-owned exchange operator; see
cuestDirectCoulombDerivativeCompute()for the shared conventions. As for J, this is the density-fitted and Grid-K exchange derivative energy definition. Each output gradient has shape (natom × 3), row-major, one per batch entry in the output buffer (size: numDensityMatrices × natom × 3) on the GPU, and is overwritten. All required temporary workspace must be allocated using the size returned bycuestDirectSymmetricExchangeDerivativeComputeWorkspaceQuery().This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Exchange operator. The operator is owned by the plan: the derivative respects
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION,CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION, andCUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA, set throughcuestDirectIntPlanParametersAttributes_tat plan creation.Compute parameters. Controlled through the two attributes of this routine’s own
cuestDirectSymmetricExchangeDerivativeComputeParameters_tobject (CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEandCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle; carries the exchange operator) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatrices[in]Pointer
Input density matrices (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on the GPU. Must not be NULL.
- outExchangeGradients[out]Pointer
Output buffer (size: numDensityMatrices × natom × 3, contiguous, row-major) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeBilinearDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices1: cuest.bindings.cuest.Pointer,
- densityMatrices2: cuest.bindings.cuest.Pointer,
- outExchangeGradients: cuest.bindings.cuest.Pointer,
Query the temporary workspace required for a direct 4-center bilinear exchange (K) gradient computation.
Fills the descriptor with the required temporary sizes for a single
cuestDirectSymmetricExchangeBilinearDerivativeCompute()call.densityMatrices1,densityMatrices2andoutExchangeGradientsmay be NULL (never dereferenced).Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle; carries the exchange operator) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density-matrix pairs in the batch. Must be >= 1.
- densityMatrices1Pointer
Optional first density matrices. May be NULL.
- densityMatrices2Pointer
Optional second density matrices (the bilinear form’s D’). May be NULL.
- outExchangeGradientsPointer
Optional output gradient buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERiftemporaryWorkspaceDescriptoror any other required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectSymmetricExchangeBilinearDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices1: cuest.bindings.cuest.Pointer,
- densityMatrices2: cuest.bindings.cuest.Pointer,
- outExchangeGradients: cuest.bindings.cuest.Pointer,
Compute the nuclear gradients of the bilinear exchange form for a batch of symmetric density-matrix pairs.
For each pair (
densityMatrices1[m],densityMatrices2[m]) this routine computes\[\nabla_A E_K^{(m)}, \qquad E_K^{(m)} = \sum_{pqrs} D^{(m)}_{pq} (pr|qs) D'^{(m)}_{rs} = \sum_{pr} D^{(m)}_{pr} K[D'^{(m)}]_{pr}\]as a pure integral-derivative contraction with the exchange operator owned by the plan (see
cuestDirectCoulombDerivativeCompute()for the shared conventions), both matrices of a pair symmetric (not checked). Each output gradient has shape (natom × 3), row-major, one per batch entry in the output buffer (size: numDensityMatrices × natom × 3) on the GPU, and is overwritten. At D’ = D the result equalscuestDirectSymmetricExchangeDerivativeCompute(). All required temporary workspace must be allocated using the size returned bycuestDirectSymmetricExchangeBilinearDerivativeComputeWorkspaceQuery().This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Exchange operator. The operator is owned by the plan: the derivative respects
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION,CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION, andCUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA, set throughcuestDirectIntPlanParametersAttributes_tat plan creation.Compute parameters. Controlled through the two attributes of this routine’s own
cuestDirectSymmetricExchangeDerivativeComputeParameters_tobject (CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEandCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.Screening. Both densities of a pair enter the Schwarz screening, each bounding its own side of the integral, so a pair with a sparse member (a SAD or delta density against a converged density) costs much less than the single-density gradient of their sum; a Schwarz threshold of 0 gives an unscreened result.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle; carries the exchange operator) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectSymmetricExchangeDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numDensityMatrices[in]int
Number of density-matrix pairs in the batch. Must be >= 1.
- densityMatrices1[in]Pointer
First input density matrices D (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on the GPU. Must not be NULL.
- densityMatrices2[in]Pointer
Second input density matrices D’ (same layout, each symmetric) on the GPU. Must not be NULL.
- outExchangeGradients[out]Pointer
Output buffer (size: numDensityMatrices × natom × 3, contiguous, row-major) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.