Unified Coulomb/Exchange Gradient#

cuest.bindings.cuestDFSymmetricDerivativeCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspace: int,
densityScale: float,
densityMatrix: cuest.bindings.cuest.Pointer,
coefficientScale: float,
numCoefficientMatrices: int,
numOccupied: list[int],
coefficientMatrices: cuest.bindings.cuest.Pointer,
outGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Compute the nuclear gradient (derivative) of the symmetric DF J/K matrices contracted with a density matrix and multiple coefficient matrices.

This routine evaluates the nuclear derivatives (gradients) of the Coulomb (J) and exchange (K) matrices in density fitting approximation, where the J matrix is contracted with a single density matrix and the K matrices are contracted with multiple occupied orbital coefficient matrices. The result is accumulated into the output gradient buffer (size: natom × 3).

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

The bare Coulomb and exchange energies are given as:

\[E_{J} = \sum_{mnrs} D_{mn} (mn|rs) D_{rs}\]
\[E_{K}^{N} = \sum_{mnrs} \sum_{ij} C_{im}^{N} C_{jn}^{N} (mn|rs) C_{ir}^{N} C_{js}^{N}\]

An effective J/K energy can be written as:

\[E_{JK} = s_D * E_{J} + \sum_{N} s_C * f_E * E_{K}^{N}\]

where:

For example, in a B3LYP RKS computation the intended usage would be:

For a PBE0 UKS computation the intended usage would be:

  • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION = 0.25

  • densityScale = 0.5

  • coefficientScale = -0.5

  • numCoefficientMatrices = 2

  • \(D_{mn} = \sum_{i} C_{im}^{\alpha} C_{in}^{\alpha} + \sum_{i} C_{im}^{\beta} C_{in}^{\beta}\)

  • \(I_{ij} = \sum_{mn} C_{im}^{\alpha} S_{mn} S_{jn}^{\alpha}\)

  • \(I_{ij} = \sum_{mn} C_{im}^{\beta} S_{mn} S_{jn}^{\beta}\)

Parameters#

handle[in]CuestHandle

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

Density-fitted integral computation plan (opaque handle).

parameters[in]cuestDFSymmetricDerivativeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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

temporaryWorkspace[in]Workspace

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

densityScale[in]float

Scaling factor for the J (Coulomb) contribution.

densityMatrix[in]Pointer

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

coefficientScale[in]float

Scaling factor for each K (exchange) contribution.

numCoefficientMatrices[in]int

Number of coefficient matrices. Must be > 0.

numOccupied[in]list of int

Number of occupied orbitals for each coefficient matrix (size: numCoefficientMatrices) on the CPU. Must not be NULL.

coefficientMatrices[in]Pointer

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

outGradient[out]Pointer

Output nuclear gradient (size: natom × 3) on the GPU. Gradient results overwrite this buffer. Must not be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestDFSymmetricDerivativeComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
temporaryWorkspaceDescriptor: int,
densityScale: float,
densityMatrix: cuest.bindings.cuest.Pointer,
coefficientScale: float,
numCoefficientMatrices: int,
numOccupied: list[int],
coefficientMatrices: cuest.bindings.cuest.Pointer,
outGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required for a DF J/K nuclear gradient computation.

This function determines the workspace required for a symmetric DF J/K gradient evaluation with the given plan, density matrix, coefficient matrices, and maximum workspace constraint. The output descriptor is filled on success and can be used to allocate host and device workspace buffers prior to calling cuestDFSymmetricDerivativeCompute().

Parameters#

handle[in]CuestHandle

cuEST handle. Must not be NULL.

plan[in]CuestDFIntPlanHandle

Density-fitted integral computation plan (opaque handle).

parameters[in]cuestDFSymmetricDerivativeComputeParameters_t

Parameters object. Must not be NULL.

variableBufferSize[in]WorkspaceDescriptor

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

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

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

densityScale[in]float

Scaling factor for the J (Coulomb) contribution.

densityMatrix[in]Pointer

Optional density matrix. May be NULL.

coefficientScale[in]float

Scaling factor for each K (exchange) contribution.

numCoefficientMatrices[in]int

Number of coefficient matrices. Must be > 0.

numOccupied[in]list of int

Array of occupied orbital counts for each coefficient matrix (size: numCoefficientMatrices). Each entry must be > 0. Must not be NULL.

coefficientMatrices[in]Pointer

Optional concatenated coefficient matrices. May be NULL.

outGradient[in]Pointer

Optional output nuclear gradient. May be NULL.

Returns#

status[out]cuestStatus_t