Exchange/Correlation#

Potential#

group ExchangeCorrelation

Functions

cuestStatus_t cuestXCPotentialRKSCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCPotentialRKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupied, const double *coefficientMatrix, double *outXCEnergy, double *outXCPotentialMatrix )#

Compute the RKS XC potential (Vxc) matrix using the supplied XC integral plan and occupied molecular orbitals.

This routine computes the XC potential matrix (Vxc) from occupied molecular orbitals. This is the RKS interface that assumes the alpha and beta spin orbitals are identical. The user must provide occupied molecular orbitals (size nocc x nao) and a preallocated output buffer (size nao × nao). The orbital basis and integration grid used are passed via the plan. All required temporary workspace must be allocated using the size returned by cuestXCPotentialRKSComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate. The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
parameters – [in] Compute parameters (cuestXCPotentialRKSComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Temporary workspace buffer for this operation.
numOccupied – [in] Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix – [in] Input coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
outXCEnergy – [out] Output (double) for the computed XC energy (size: 1) on the CPU. Must not be NULL. This element is overwritten by the calculation results.
outXCPotentialMatrix – [out] Output buffer for computed XC potential matrix (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCPotentialRKSComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCPotentialRKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupied, const double *coefficientMatrix, double *outXCEnergy, double *outXCPotentialMatrix )#

Query the temporary workspace required (in bytes) for an XC potential matrix computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided plan and pair list. Only sizes are computed; output and orbital buffers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCPotentialRKSComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupied – [in] Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix – [in] Input coefficient matrix. May be NULL.
outXCEnergy – [in] Output (double) for the computed XC energy. May be NULL.
outXCPotentialMatrix – [in] Output buffer for computed XC potential matrix. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCPotentialUKSCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCPotentialUKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupiedAlpha, uint64_t numOccupiedBeta, const double *coefficientMatrixAlpha, const double *coefficientMatrixBeta, double *outXCEnergy, double *outXCPotentialMatrixAlpha, double *outXCPotentialMatrixBeta )#

Compute the UKS XC potential (Vxc) matrix using the supplied XC integral plan and occupied molecular orbitals.

This routine computes the UKS XC potential matrices (Vxc) from occupied molecular orbitals. This is the UKS interface that allows the alpha and beta spin orbitals to be different. The user must provide occupied molecular orbitals (size nocc x nao) and preallocated output buffers (size nao × nao). The orbital basis and integration grid used are passed via the plan. All required temporary workspace must be allocated using the size returned by cuestXCPotentialUKSComputeWorkspaceQuery.

Alpha and beta coefficient matrices must always be provided with non-zero numbers of occupied orbitals. Cases without beta (or alpha) electrons (hydrogen atom, for example), can be handled by passing in a coefficient matrix containing only zeros.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate. The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
parameters – [in] Compute parameters (cuestXCPotentialUKSComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Temporary workspace buffer for this operation.
numOccupiedAlpha – [in] Number of alpha occupied orbitals (rows in alpha coefficient matrix); must be greater than zero.
numOccupiedBeta – [in] Number of beta occupied orbitals (rows in beta coefficient matrix); must be greater than zero.
coefficientMatrixAlpha – [in] Input alpha coefficient matrix (size: numOccupiedAlpha × nao). Must not be NULL.
coefficientMatrixBeta – [in] Input beta coefficient matrix (size: numOccupiedBeta × nao). Must not be NULL.
outXCEnergy – [out] Output (double) for the computed XC energy (size: 1) on the CPU. Must not be NULL.
outXCPotentialMatrixAlpha – [out] Output buffer for computed XC potential matrix (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
outXCPotentialMatrixBeta – [out] Output buffer for computed XC potential matrix (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCPotentialUKSComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCPotentialUKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupiedAlpha, uint64_t numOccupiedBeta, const double *coefficientMatrixAlpha, const double *coefficientMatrixBeta, double *outXCEnergy, double *outXCPotentialMatrixAlpha, double *outXCPotentialMatrixBeta )#

Query the temporary workspace required (in bytes) for an XC potential matrix computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided plan and pair list. Only sizes are computed; output and orbital buffers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCPotentialUKSComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupiedAlpha – [in] Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta – [in] Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha – [in] Input alpha coefficient matrix. May be NULL.
coefficientMatrixBeta – [in] Input beta coefficient matrix. May be NULL.
outXCEnergy – [in] Output (double) for the computed XC energy. May be NULL.
outXCPotentialMatrixAlpha – [in] Output buffer for computed alpha XC potential matrix. May be NULL.
outXCPotentialMatrixBeta – [in] Output buffer for computed beta XC potential matrix. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

Gradient#

group ExchangeCorrelationGrad

Functions

cuestStatus_t cuestXCDerivativeRKSCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCDerivativeRKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupied, const double *coefficientMatrix, double *outGradient )#

Compute the derivative of the RKS XC energy (Exc) using the supplied XC integral plan and occupied molecular orbitals.

This routine computes the XC gradient from occupied molecular orbitals. This is the RKS interface that assumes the alpha and beta spin orbitals are identical. The user must provide occupied molecular orbitals (size nocc x nao) and a preallocated output buffer (size natom × 3). The orbital basis and integration grid used are passed via the plan. All required temporary workspace must be allocated using the size returned by cuestXCDerivativeRKSComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate. The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC gradient is evaluated.
parameters – [in] Compute parameters (cuestXCDerivativeRKSComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Temporary workspace buffer for this operation.
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.
outGradient – [out] Output buffer for computed XC gradient (size: natom × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDerivativeRKSComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCDerivativeRKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupied, const double *coefficientMatrix, double *outGradient )#

Query the temporary workspace required (in bytes) for an XC derivative computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided plan. Only sizes are computed; output and orbital buffers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCDerivativeRKSComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupied – [in] Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix – [in] Input coefficient matrix. May be NULL.
outGradient – [in] Output buffer for computed XC gradient. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDerivativeUKSCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCDerivativeUKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupiedAlpha, uint64_t numOccupiedBeta, const double *coefficientMatrixAlpha, const double *coefficientMatrixBeta, double *outGradient )#

Compute the derivative of the UKS XC energy (Exc) using the supplied XC integral plan and occupied molecular orbitals.

This routine computes the UKS XC gradient from occupied molecular orbitals. This is the UKS interface that allows the alpha and beta spin orbitals to be different. The user must provide occupied molecular orbitals (size nocc x nao) and preallocated output buffer (size natom × 3). The orbital basis and integration grid used are passed via the plan. All required temporary workspace must be allocated using the size returned by cuestXCDerivativeUKSComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate. The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC gradient is evaluated.
parameters – [in] Compute parameters (cuestXCDerivativeUKSComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Temporary workspace buffer for this operation.
numOccupiedAlpha – [in] Number of alpha occupied orbitals (rows in alpha coefficient matrix); must be greater than zero.
numOccupiedBeta – [in] Number of beta occupied orbitals (rows in beta coefficient matrix); must be greater than zero.
coefficientMatrixAlpha – [in] Input alpha coefficient matrix (size: numOccupiedAlpha × nao) on GPU. Must not be NULL.
coefficientMatrixBeta – [in] Input beta coefficient matrix (size: numOccupiedBeta × nao) on GPU. Must not be NULL.
outGradient – [out] Output buffer for computed XC gradient (size: natom × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDerivativeUKSComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCDerivativeUKSComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupiedAlpha, uint64_t numOccupiedBeta, const double *coefficientMatrixAlpha, const double *coefficientMatrixBeta, double *outGradient )#

Query the temporary workspace required (in bytes) for an XC derivative computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided plan. Only sizes are computed; output and orbital buffers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCDerivativeUKSComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupiedAlpha – [in] Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta – [in] Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha – [in] Input alpha coefficient matrix. May be NULL.
coefficientMatrixBeta – [in] Input beta coefficient matrix. May be NULL.
outGradient – [in] Output buffer for computed XC gradient. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.
CUEST_STATUS_INVALID_ARGUMENT if numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION if cuestXCIntPlanParametersFunctional_t is CUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF (set in the cuestXCIntPlan_t).
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

Advanced Functions#

group ExchangeCorrelationAdvanced

Functions

cuestStatus_t cuestXCDerivativeCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCDerivativeComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupied, const double *coefficientMatrix, const double *gridXCPotential, double *outBasisGradient, double *outGridGradient )#

Compute the exchange-correlation (XC) derivative contributions for analytical gradients.

This routine computes the gradient contributions of the exchange–correlation (XC) energy with respect to the atomic coordinates. It uses the provided XC potential on the molecular integration grid, the molecular orbital coefficients, and the XC integral plan.

The form and dimensionality of the input gridXCPotential depend on the chosen approximation type (LDA, GGA, or meta-GGA) - see cuestXCPotentialCompute. All temporary workspace must be preallocated according to the size returned by cuestXCDerivativeComputeWorkspaceQuery.

Important: This function does not apply the integration weights to the user-supplied XC potential. The user must apply the total integration weights, which can be obtained by calling cuestXCIntegrationWeightCompute.

In order to compute the derivative of the XC energy,

\[ \frac{\rm d}{{\rm d}R_A} E_{xc} = \frac{\rm d}{{\rm d}R_A} \sum_{P}^{\rm npoint} w_{P} e_{xc,P} \]

where \( A \) indexes atom centers and \( P \) are the grid points, there are two terms to evaluate.

\[ \frac{\rm d}{{\rm d}R_A} E_{xc} = \sum_{P}^{\rm npoint} \frac{{\rm d} w_{P}}{{\rm d}R_A} e_{xc,P} + \sum_{P}^{\rm npoint} w_{P} \frac{{\rm d} e_{xc,P}}{{\rm d}R_A} \]

Contributions from the second term, \( \sum_{P}^{\rm npoint} w_{P} \frac{{\rm d} e_{xc,P}}{{\rm d}R_A} \) are evaluated by this function. Specifically, this function computes outBasisGradient computed as \( \sum_{P}^{\rm npoint} w_{P} \frac{\partial e_{xc,P}}{\partial R_A} \), where \( R_A \) are the basis function centers (treated as separate from grid point centers). It also computes outGridGradient as \( \sum_{P}^{\rm npoint} w_{P} \frac{\partial e_{xc,P}}{\partial R_Q} \), where \( R_Q \) are the grid points. The outBasisGradient contributed directly to the derivative of the XC energy. The outGridGradient array should be included in a subsequent call to cuestXCGridDerivativeCompute to assemble additional contributions to the gradient.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCDerivativeComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Preallocated temporary workspace buffer for this operation. Must not be NULL.
numOccupied – [in] Number of occupied orbitals in the input coefficient matrix. Must be greater than zero.
coefficientMatrix – [in] Input orbital coefficient matrix (size: numOccupied × nao) on GPU. Must not be NULL.
gridXCPotential – [in] Input grid exchange-correlation potential array (size: npoint × ndim) on GPU. Must not be NULL.
outBasisGradient – [out] Output buffer for basis function center gradient contributions (size: natom × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
outGridGradient – [out] Output buffer for grid point gradient contributions (size: npoint × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if handle types are incorrect;
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero or approximation invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDerivativeComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCDerivativeComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupied, const double *coefficientMatrix, const double *gridXCPotential, double *outBasisGradient, double *outGridGradient )#

Query the temporary workspace required (in bytes) for an XC derivative computation.

Determines the required GPU workspace size to compute exchange–correlation (XC) energy gradient contributions. This query prepares for cuestXCDerivativeCompute by reporting the necessary temporary memory allocation given the chosen approximation and molecular system.

Only workspace sizes are computed; inputs/outputs may be NULL. The same variableBufferSize descriptor must be reused for the corresponding compute call.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCDerivativeComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor with required workspace sizes (in bytes). Must not be NULL.
numOccupied – [in] Number of occupied orbitals. Must be greater than zero.
coefficientMatrix – [in] Input coefficient matrix. May be NULL.
gridXCPotential – [in] Input grid XC potential array. May be NULL.
outBasisGradient – [in] Output buffer for basis function center gradient contributions. May be NULL.
outGridGradient – [in] Output buffer for grid point gradient contributions. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if handle types are incorrect;
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero or approximation invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCGridDerivativeCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCGridDerivativeComputeParameters_t parameters, cuestWorkspace_t *temporaryWorkspace, const double *gridXCEnergy, const double *gridGradient, double *outGradient )#

Compute total XC energy gradient from grid XC energy and its spatial derivatives.

This routine combines grid-resolved XC energy densities and their spatial gradients to produce the total (molecular) XC gradient with respect to atomic coordinates. It serves as the final step in assembling analytical derivatives after the grid-level contributions have been computed.

The operation uses the molecular grid and AO basis data embedded in the provided XC plan. All required workspace should be preallocated according to the size returned by cuestXCGridDerivativeComputeWorkspaceQuery.

Important: This function does apply integration weights to the user-supplied XC energy. The user must supply the bare \( e_{xc,P} \) array as shown in:

\[ E_{xc} = \sum_{P}^{\rm npoint} w_{P} e_{xc,P} \]

This function is expected to be called after cuestXCDerivativeCompute. The purpose of this function is to evaluate contributions to the XC gradient resulting from derivatives of the integration weight \( \sum_{P}^{\rm npoint} \frac{{\rm d} w_{P}}{{\rm d}R_A} e_{xc,P} \) and to incorporate contributions from grid point motion: \( \sum_{P}^{\rm npoint} w_{P} \frac{\partial e_{xc,P}}{\partial R_Q} \frac{\partial R_Q}{\partial R_A} \). Here \( R_Q \) are the grid points and \( R_A \) are the atomic centers defining the grid.

The sum of outGradient computed by this routine and outBasisGradient computed by cuestXCDerivativeCompute (scaled appropriately) is the derivative of the XC energy: \( \frac{\rm d}{{\rm d}R_A} E_{xc} \). In the case of UKS calculations, cuestXCDerivativeCompute will need to be called twice, but cuestXCGridDerivativeCompute only needs to be called once.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCGridDerivativeComputeParameters_t). Must not be NULL
temporaryWorkspace – [in] Preallocated GPU workspace buffer for temporary data. Must not be NULL.
gridXCEnergy – [in] Input grid XC energy density values (size: npoint × 1) on GPU. Must not be NULL.
gridGradient – [in] Input grid spatial gradient contributions (size: npoint × 3) on GPU. Must not be NULL.
outGradient – [out] Output total (atomic) gradient of XC energy (size: natom × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if handle types are incorrect;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCGridDerivativeComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCGridDerivativeComputeParameters_t parameters, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, const double *gridXCEnergy, const double *gridGradient, double *outGradient )#

Query the temporary workspace required (in bytes) for an XC grid derivative computation.

Estimates the GPU memory workspace required to compute the grid-based exchange–correlation (XC) gradient using molecular grid data. This function reports the necessary device buffer size for cuestXCGridDerivativeCompute.

Only workspace sizes are computed; input and output buffers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCGridDerivativeComputeParameters_t). Must not be NULL
temporaryWorkspaceDescriptor – [out] Output descriptor with required temporary workspace sizes (in bytes). Must not be NULL.
gridXCEnergy – [in] Input grid XC energy density. May be NULL.
gridGradient – [in] Input grid gradient contributions. May be NULL.
outGradient – [in] Output total (atomic) gradient array. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if handle types are incorrect;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCIntegrationGridCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCIntegrationGridComputeParameters_t parameters, cuestWorkspace_t *temporaryWorkspace, double *outGridPoints )#

Compute molecular integration grid point coordinates.

This routine retrieves the Cartesian coordinates of each molecular grid point used for exchange–correlation (XC) integration. These are the grid points used by the corresponding XC integral plan.

The resulting coordinates are written to a user-provided output buffer of shape (npoint × 3), containing the x, y, z coordinates of each grid point.

Temporary device workspace must be preallocated based on the size returned by cuestXCIntegrationGridComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCIntegrationGridComputeParameters_t) Must not be NULL
temporaryWorkspace – [in] Preallocated GPU workspace buffer. Must not be NULL.
outGridPoints – [out] Output buffer for computed grid point coordinates (size: npoint × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if the handle or plan type is incorrect;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCIntegrationGridComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, const cuestXCIntegrationGridComputeParameters_t parameters, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, double *outGridPoints )#

Query temporary workspace requirements for grid coordinate computation.

Determines the GPU memory workspace needed to generate the coordinates of molecular integration grid points defined by the provided XC integral plan. This function must be called before cuestXCIntegrationGridCompute to ensure sufficient allocation.

Only workspace sizes are computed; input and output pointers may be NULL.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
parameters – [in] Compute parameters (cuestXCIntegrationGridComputeParameters_t) Must not be NULL
temporaryWorkspaceDescriptor – [out] Output descriptor for required workspace sizes (in bytes). Must not be NULL.
outGridPoints – [in] Output array for grid point coordinates. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if handles are of incorrect type;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCIntegrationWeightCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCIntegrationWeightComputeParametersWeightType_t weightType, const cuestXCIntegrationWeightComputeParameters_t parameters, cuestWorkspace_t *temporaryWorkspace, double *outGridWeights )#

Compute molecular integration weights for XC quadrature.

This routine computes the integration weights associated with each grid point in the molecular integration grid used for exchange–correlation (XC) integration. The weights depend on the selected weighting scheme, specified by weightType.

Supported weighting schemes include:

CUEST_XCINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_TOTAL — total integration weight (angular x radial x Becke);
CUEST_XCINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_BECKE — Becke atomic partition weights;
CUEST_XCINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_QUADRATURE — quadrature-only weights (angular x radial).

The result is written to outGridWeights (size: npoint × 1). Temporary workspace must be preallocated based on cuestXCIntegrationWeightComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
weightType – [in] Weight scheme to compute (total, Becke, quadrature).
parameters – [in] Compute parameters (cuestXCIntegrationWeightComputeParameters_t) Must not be NULL
temporaryWorkspace – [in] Preallocated GPU workspace buffer for temporary data. Must not be NULL.
outGridWeights – [out] Output buffer for integration weights (size: npoint × 1) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if the handle or plan type is invalid;
CUEST_STATUS_INVALID_ARGUMENT if weightType is unrecognized;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCIntegrationWeightComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCIntegrationWeightComputeParametersWeightType_t weightType, const cuestXCIntegrationWeightComputeParameters_t parameters, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, double *outGridWeights )#

Query the temporary workspace required (in bytes) for computing XC integration weights.

Determines GPU memory workspace requirements to compute integration weights on the molecular grid as defined by the provided XC integral plan. The required workspace depends on the grid structure and selected weighting scheme.

This query should be executed before calling cuestXCIntegrationWeightCompute to ensure that sufficient device memory is available.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
weightType – [in] Weight scheme to compute (total, Becke, quadrature).
parameters – [in] Compute parameters (cuestXCIntegrationWeightComputeParameters_t) Must not be NULL
temporaryWorkspaceDescriptor – [out] Output descriptor for required temporary workspace sizes (in bytes). Must not be NULL.
outGridWeights – [in] Optional output buffer for computed weights. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if the handle or plan type is incorrect;
CUEST_STATUS_INVALID_ARGUMENT if weightType is unsupported;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDensityCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCDensityComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, uint64_t numOccupied, const double *coefficientMatrix, double *outGridDensity )#

Compute the electron density on the integration grid using the provided XC integral plan and molecular orbitals.

This routine evaluates the electronic density (and its derivatives, when applicable) on the molecular integration grid. The computation depends on the chosen approximation level (LDA, GGA, or meta-GGA), which determines the number of quantities calculated per grid point. The density is computed from the occupied molecular orbitals.

Each approximation produces an output array of shape (npoint × ndim), where:

LDA: ndim = 1 ( \( \rho \));
GGA: ndim = 4 ( \( \rho, \nabla_{x}\rho, \nabla_{y}\rho, \nabla_{z}\rho \));
meta-GGA: ndim = 5 ( \( \rho, \nabla_{x}\rho, \nabla_{y}\rho, \nabla_{z}\rho, \tau \)).

The returned density does include integration weights. To obtain the total number of electrons, evaluate:

\[ N_{elec} = \sum_{P}^{\rm npoint} w_{P} \rho_{P} \]

where, \( w_{P} \) is the total integration weight that can be obtained by calling cuestXCIntegrationWeightCompute.

All required workspace must first be allocated according to the size returned by cuestXCDensityComputeWorkspaceQuery, which must be called before invoking this function.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCDensityComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Preallocated temporary workspace buffer for this operation. Must not be NULL.
numOccupied – [in] Number of occupied orbitals (rows in coefficientMatrix). Must be greater than zero.
coefficientMatrix – [in] Input orbital coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
outGridDensity – [out] Output buffer for computed density or density derivatives on the grid (size: npoint × ndim) on the GPU. Must not be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are of incorrect type;
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero or approximation is invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCDensityComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCDensityComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, uint64_t numOccupied, const double *coefficientMatrix, double *outGridDensity )#

Query the temporary workspace required (in bytes) for an XC density computation.

Determines the GPU memory requirements for computing the electron density (and its derivatives) on the molecular grid using the provided XC integral plan and approximation type. Only memory requirements are estimated; no actual computation is performed. Input and output pointers may be NULL.

This call must precede cuestXCDensityCompute to ensure that sufficient temporary memory is available.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCDensityComputeParameters_t) Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor with required workspace sizes (in bytes). Must not be NULL.
numOccupied – [in] Number of occupied orbitals (rows in coefficientMatrix). Must be greater than zero.
coefficientMatrix – [in] Input orbital coefficient matrix. May be NULL.
outGridDensity – [in] Output buffer for computed density values. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are of incorrect type;
CUEST_STATUS_INVALID_ARGUMENT if numOccupied is zero or approximation is invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCPotentialCompute( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCPotentialComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspace_t *temporaryWorkspace, const double *gridXCPotential, double *outXCPotentialMatrix )#

Compute the XC potential matrix (Vxc) from a precomputed XC potential on the integration grid.

This routine constructs the exchange-correlation potential matrix in the AO basis from a grid representation of the XC potential. The input grid potential should correspond to the same grid and basis information specified by the provided XC integral plan. The dimensionality of the grid potential depends on the selected approximation (LDA, GGA, meta-GGA).

Each approximation requires an input array of shape (npoint × ndim) with derivatives ordered as:

LDA: ndim = 1 ( \( \rho \));
GGA: ndim = 4 ( \( \rho, \nabla_{x}\rho, \nabla_{y}\rho, \nabla_{z}\rho \));
meta-GGA: ndim = 5 ( \( \rho, \nabla_{x}\rho, \nabla_{y}\rho, \nabla_{z}\rho, \tau \)).

All required temporary workspace must first be allocated using the size returned by cuestXCPotentialComputeWorkspaceQuery.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCPotentialComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace – [in] Preallocated temporary workspace buffer for this operation. Must not be NULL.
gridXCPotential – [in] Input XC potential on the grid (size: npoint × ndim) on GPU. Must not be NULL.
outXCPotentialMatrix – [out] Output buffer for computed XC potential matrix (size: nao × nao) on GPU. Must not be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are of incorrect type;
CUEST_STATUS_INVALID_ARGUMENT if approximation is invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestXCPotentialComputeWorkspaceQuery( cuestHandle_t handle, const cuestXCIntPlan_t plan, cuestXCAdvancedComputeParametersApproximation_t approximation, const cuestXCPotentialComputeParameters_t parameters, const cuestWorkspaceDescriptor_t *variableBufferSize, cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor, const double *gridXCPotential, double *outXCPotentialMatrix )#

Query the temporary workspace required (in bytes) for an XC potential matrix computation.

This function returns the GPU workspace memory requirements for constructing the exchange-correlation (XC) potential matrix in the AO basis from a given XC potential on the grid. Only workspace sizes are computed; the input and output pointers may be NULL.

This query must be executed prior to calling cuestXCPotentialCompute.

Parameters:

handle – [in] cuEST handle. Must not be NULL.
plan – [in] XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate.
approximation – [in] Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters – [in] Compute parameters (cuestXCPotentialComputeParameters_t). Must not be NULL
variableBufferSize – [in] User-provided descriptor for the variable buffer size (host and device). Must not be NULL. 2 GB is a good default value for device memory. There are diminishing returns for very large values of the variableBufferSize. Some static allocations are made outside of what is controlled by the variableBufferSize. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor – [out] Output descriptor for required temporary workspace sizes (in bytes). Must not be NULL.
gridXCPotential – [in] Input XC potential on the grid. May be NULL.
outXCPotentialMatrix – [in] Output buffer for computed XC potential matrix. May be NULL.

Returns:

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;
CUEST_STATUS_NULL_POINTER if any required pointer is NULL;
CUEST_STATUS_INVALID_TYPE if opaque handles are of incorrect type;
CUEST_STATUS_INVALID_ARGUMENT if approximation is invalid;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.