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
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] 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 NULLCreate with
cuestParametersCreate()usingCUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_SLICE_COUNTuint64_tNumber of slices used in cuBLAS emulated GEMMs. Mantissa bit count = 8 * slices - 1.
Default:
5CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_MODULUS_COUNTuint64_tNumber of moduli used in custom Ozaki-II emulated GEMMs.
Default:
8
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_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.
- 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 NULLCreate with
cuestParametersCreate()usingCUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_SLICE_COUNTuint64_tNumber of slices used in cuBLAS emulated GEMMs. Mantissa bit count = 8 * slices - 1.
Default:
5CUEST_DFSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_MODULUS_COUNTuint64_tNumber of moduli used in custom Ozaki-II emulated GEMMs.
Default:
8
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_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.
- 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
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.- 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 NULLCreate with
cuestParametersCreate()usingCUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_SLICE_COUNTuint64_tNumber of slices used in cuBLAS emulated GEMMs. Mantissa bit count = 8 * slices - 1.
Default:
5CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_MODULUS_COUNTuint64_tNumber of moduli used in custom Ozaki-II emulated GEMMs.
Default:
8
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_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.
- 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 NULLCreate with
cuestParametersCreate()usingCUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_SLICE_COUNTuint64_tNumber of slices used in cuBLAS emulated GEMMs. Mantissa bit count = 8 * slices - 1.
Default:
5CUEST_DFNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS_INT8_MODULUS_COUNTuint64_tNumber of moduli used in custom Ozaki-II emulated GEMMs.
Default:
8
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_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.
- cuestStatus_t cuestGridKSymmetricExchangeCompute(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKSymmetricExchangeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
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
cuestGridKNonsymmetricExchangeComputefor 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 size returned by
cuestGridKSymmetricExchangeComputeWorkspaceQuery.
- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKSymmetricExchangeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKSYMMETRICEXCHANGECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and exchange matrices produced; must be greater than zero.
densityMatrices – [in] Input stacked symmetric density matrices (size:
numDensityMatrices× nao × nao) on GPU. Must not be NULL.outExchangeMatrices – [out] Output buffer for the AO exchange matrices (size:
numDensityMatrices× nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results; block \( i \) receives the symmetric \( K^{i} \).
- Returns:
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.
- cuestStatus_t cuestGridKSymmetricExchangeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKSymmetricExchangeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
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 subsequentcuestGridKSymmetricExchangeComputecall.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKSymmetricExchangeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKSYMMETRICEXCHANGECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes (host and device). Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and exchange matrices produced; must be greater than zero.
densityMatrices – Optional pointer to the stacked density matrix buffer (may be NULL).
outExchangeMatrices – Optional pointer to the stacked output exchange matrix buffer (may be NULL).
- Returns:
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.
- cuestStatus_t cuestGridKNonsymmetricExchangeCompute(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKNonsymmetricExchangeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
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 size returned by
cuestGridKNonsymmetricExchangeComputeWorkspaceQuery.
- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKNonsymmetricExchangeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and exchange matrices produced; must be greater than zero.
densityMatrices – [in] Input stacked density matrices (size:
numDensityMatrices× nao × nao) on GPU. Must not be NULL.outExchangeMatrices – [out] Output buffer for the AO exchange matrices (size:
numDensityMatrices× nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results; block \( i \) receives the operator-symmetrized \( K^{i} \).
- Returns:
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.
- cuestStatus_t cuestGridKNonsymmetricExchangeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKNonsymmetricExchangeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
Query the temporary workspace required (in bytes) for the calculation of nonsymmetric Grid-K exchange matrices.
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 subsequentcuestGridKNonsymmetricExchangeComputecall.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKNonsymmetricExchangeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKNONSYMMETRICEXCHANGECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes (host and device). Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and exchange matrices produced; must be greater than zero.
densityMatrices – Optional pointer to the stacked density matrix buffer (may be NULL).
outExchangeMatrices – Optional pointer to the stacked output exchange matrix buffer (may be NULL).
- Returns:
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.
- cuestStatus_t cuestGridKSymmetricExchangeDerivativeCompute(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKSymmetricExchangeDerivativeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outGradients
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.
When
CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRICis used, theCUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFFmay lead to some orthogonalized functions being discarded (i.e. the linearly dependent functions). The intersubspace between the retained and discarded orthogonal functions is not included in the nuclear gradient. This is done intentionally to avoid the potential for singularities in the eigenvector response if many eigenvalues are clustered near the cutoff value. It is expected that the neglect of this term introduces errors similar in magnitude to the use of canonical orthogonalization in the SCF energy and gradient (where these response contributions are also typically neglected).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 size returned by
cuestGridKSymmetricExchangeDerivativeComputeWorkspaceQuery.
- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKSymmetricExchangeDerivativeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and gradients produced; must be greater than zero.
densityMatrices – [in] Input stacked symmetric density matrices (size:
numDensityMatrices× nao × nao) on GPU. Must not be NULL.outGradients – [out] Output buffer for the nuclear gradients (size:
numDensityMatrices× numAtoms × 3) on 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:
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.
- cuestStatus_t cuestGridKSymmetricExchangeDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestGridKIntPlan_t plan,
- const cuestGridKSymmetricExchangeDerivativeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outGradients
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 subsequentcuestGridKSymmetricExchangeDerivativeComputecall.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Grid-K integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestGridKSymmetricExchangeDerivativeComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_GRIDKSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. There are no configurable attributes.variableBufferSize – [in] 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.
temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes (host and device). Must not be NULL.
numDensityMatrices – [in] Number of density matrices provided and gradients produced; must be greater than zero.
densityMatrices – Optional pointer to the stacked density matrix buffer (may be NULL).
outGradients – Optional pointer to the stacked output gradient buffer (may be NULL).
- Returns:
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.
- group DirectExchange
Functions
- cuestStatus_t cuestDirectSymmetricExchangeCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
Compute symmetric AO exchange (K) matrices directly from 4-center integrals for a batch of symmetric density matrices.
Computes, for each density matrix m in the batch,
\[ K^{(m)}_{pr} = \sum_{qs} (pq|rs) D^{(m)}_{qs} \]with the plan-owned exchange operator (set through the plan parameters, see cuestDirectIntPlanParametersAttributes_t). Every density matrix in the batch must be symmetric; a nonsymmetric density gives undefined results.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.
On failure the contents of
outExchangeMatricesare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle; carries the exchange operator). Must not be NULL.
parameters – [in] Compute parameters (
cuestDirectSymmetricExchangeComputeParameters_t; attributes in cuestDirectSymmetricExchangeComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation (size from
cuestDirectSymmetricExchangeComputeWorkspaceQuery). Must not be NULL.numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on GPU. Must not be NULL.
outExchangeMatrices – [out] Output buffer (size: numDensityMatrices × nao × nao, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectSymmetricExchangeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeMatrices
Workspace query for
cuestDirectSymmetricExchangeCompute.Fills the descriptor with the temporary workspace sizes required by
cuestDirectSymmetricExchangeCompute.densityMatricesandoutExchangeMatricesmay be NULL (never dereferenced).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices. May be NULL.
outExchangeMatrices – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectSymmetricExchangeDerivativeCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeDerivativeComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeGradients
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 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; seecuestDirectCoulombDerivativeComputefor 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, and is overwritten.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.
On failure the contents of
outExchangeGradientsare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle; carries the exchange operator). Must not be NULL.
parameters – [in] Compute parameters (
cuestDirectSymmetricExchangeDerivativeComputeParameters_t; attributes in cuestDirectSymmetricExchangeDerivativeComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on GPU. Must not be NULL.
outExchangeGradients – [out] Output buffer (size: numDensityMatrices × natom × 3, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectSymmetricExchangeDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeDerivativeComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outExchangeGradients
Workspace query for
cuestDirectSymmetricExchangeDerivativeCompute.Fills the descriptor with the temporary workspace sizes required by
cuestDirectSymmetricExchangeDerivativeCompute.densityMatricesandoutExchangeGradientsmay be NULL (never dereferenced).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle; carries the exchange operator). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices. May be NULL.
outExchangeGradients – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectSymmetricExchangeBilinearDerivativeCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeDerivativeComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices1,
- const double *densityMatrices2,
- double *outExchangeGradients
Compute the nuclear gradients of the bilinear exchange form at fixed density coefficients for a batch of symmetric density-matrix pairs, directly from 4-center integral derivatives.
For each pair (D, D’) = (
densityMatrices1[m],densityMatrices2[m]) this 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 plan-owned exchange operator; seecuestDirectCoulombDerivativeComputefor the shared conventions. Each output gradient has shape (natom, 3), row-major, one per pair, and is overwritten. Both matrices of a pair must be symmetric (not checked). At D’ = D the result equalscuestDirectSymmetricExchangeDerivativeCompute(the exchange-energy gradient). Both densities of a pair enter the Schwarz screening ofparameters, 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.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.
On failure the contents of
outExchangeGradientsare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle; carries the exchange operator). Must not be NULL.
parameters – [in] Compute parameters (
cuestDirectSymmetricExchangeDerivativeComputeParameters_t; attributes in cuestDirectSymmetricExchangeDerivativeComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density-matrix pairs in the batch. Must be >= 1.
densityMatrices1 – [in] First density matrices D (size: numDensityMatrices × nao × nao, contiguous, each symmetric) on GPU. Must not be NULL.
densityMatrices2 – [in] Second density matrices D’ (same layout, each symmetric) on GPU. Must not be NULL.
outExchangeGradients – [out] Output buffer (size: numDensityMatrices × natom × 3, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectSymmetricExchangeBilinearDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectSymmetricExchangeDerivativeComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices1,
- const double *densityMatrices2,
- double *outExchangeGradients
Workspace query for
cuestDirectSymmetricExchangeBilinearDerivativeCompute.Fills the descriptor with the temporary workspace sizes required by
cuestDirectSymmetricExchangeBilinearDerivativeCompute.densityMatrices1,densityMatrices2andoutExchangeGradientsmay be NULL (never dereferenced).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle; carries the exchange operator). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTSYMMETRICEXCHANGEDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density-matrix pairs in the batch. Must be >= 1.
densityMatrices1 – [in] First density matrices. May be NULL.
densityMatrices2 – [in] Second density matrices. May be NULL.
outExchangeGradients – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.