Non-local Correlation#

group NonLocalCorrelation

Functions

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

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

This routine computes the XC potential matrix (Vxc) from the occupied molecular orbitals. This is the RKS interface that assumes the alpha and beta spin densities are identical. The user must provide preallocated 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 cuestNonlocalXCPotentialRKSComputeWorkspaceQuery.

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 does not affect this compute routine.

  • parameters – [in] cuestNonlocalXCPotentialRKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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.

  • outXCEnergy – [out] Output (double) for the computed XC energy (size: 1) on CPU. Must not be NULL.

  • outXCPotentialMatrix – [out] Output buffer for computed XC potential matrix (size: nao × nao) 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCPotentialRKSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCPotentialRKSComputeParameters_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 a nonlocal 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] cuestNonlocalXCPotentialRKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCPotentialUKSCompute(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCPotentialUKSComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numOccupiedAlpha,
uint64_t numOccupiedBeta,
const double *coefficientMatrixAlpha,
const double *coefficientMatrixBeta,
double *outXCEnergy,
double *outXCPotentialMatrix
)#

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

This routine computes the UKS XC potential matrix (Vxc) from occupied molecular orbitals. This is the UKS interface that allows the alpha and beta spin densities to be different. The user must provide preallocated occupied molecular orbitals (size: noccA x nao and noccB x nao) and 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 cuestNonlocalXCPotentialUKSComputeWorkspaceQuery.

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 does not affect this compute routine.

  • parameters – [in] cuestNonlocalXCPotentialUKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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.

  • outXCEnergy – [out] Output (double) for the computed XC energy (size: 1) on CPU. Must not be NULL.

  • outXCPotentialMatrix – [out] Output buffer for computed XC potential matrix (size: nao × nao) 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCPotentialUKSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCPotentialUKSComputeParameters_t parameters,
const cuestWorkspaceDescriptor_t *variableBufferSize,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numOccupiedAlpha,
uint64_t numOccupiedBeta,
const double *coefficientMatrixAlpha,
const double *coefficientMatrixBeta,
double *outXCEnergy,
double *outXCPotentialMatrix
)#

Query the temporary workspace required (in bytes) for a nonlocal 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] cuestNonlocalXCPotentialUKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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.

  • 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 numOccupiedAlpha or numOccupiedBeta is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

group NonLocalCorrelationGrad

Functions

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

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

This routine computes the XC gradient from the occupied molecular orbitals. This is the RKS interface that assumes the alpha and beta spin densities are identical. The user must provide preallocated 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 cuestNonlocalXCDerivativeRKSComputeWorkspaceQuery.

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 does not affect this compute routine.

  • parameters – [in] cuestNonlocalXCDerivativeRKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCDerivativeRKSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCDerivativeRKSComputeParameters_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 a nonlocal 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] cuestNonlocalXCDerivativeRKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCDerivativeUKSCompute(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCDerivativeUKSComputeParameters_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 nonlocal UKS XC energy (Exc) using the supplied XC integral plan and occupied molecular orbitals.

This routine computes the UKS nonlocal XC gradient from occupied molecular orbitals. This is the UKS interface that allows the alpha and beta spin densities to be different. The user must provide preallocated occupied molecular orbitals (size noccA x nao and noccB 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 cuestNonlocalXCDerivativeUKSComputeWorkspaceQuery.

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 does not affect this compute routine.

  • parameters – [in] cuestNonlocalXCDerivativeUKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestNonlocalXCDerivativeUKSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestXCIntPlan_t plan,
const cuestNonlocalXCDerivativeUKSComputeParameters_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 a nonlocal 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] cuestNonlocalXCDerivativeUKSComputeParameters_t defines the details of the nonlocal XC functional.

  • 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. 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 (size: numOccupiedAlpha × nao) on GPU. May be NULL.

  • coefficientMatrixBeta – [in] Input beta coefficient matrix (size: numOccupiedBeta × nao) on GPU. May be NULL.

  • outGradient – [in] Output buffer for computed XC gradient (size: natom × 3) on GPU. 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 or CUEST_STATUS_UNKNOWN_ERROR otherwise.