Exchange/Correlation#

XC Potential#

cuest.bindings.cuestXCPotentialRKSCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outXCEnergy: object, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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

This is the RKS interface that assumes the alpha and beta spin densities are identical. The user must provide:

a preallocated density matrix (size: nao × nao)
occupied molecular orbitals (size: nocc x nao)
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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCPotentialRKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]Workspace: Temporary workspace buffer for this operation.
numOccupied[in]int: Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
outXCEnergy[out]Pointer: Pointer for the computed XC energy (size: 1) on the CPU. Must not be NULL.
outXCPotentialMatrix[out]Pointer: 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#

status[out]cuestStatus_t

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.

cuest.bindings.cuestXCPotentialRKSComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outXCEnergy: object, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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 density buffers may be NULL.

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCPotentialRKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupied[in]int: Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix. May be NULL.
outXCEnergy[in]Pointer: Pointer for the computed XC energy. May be NULL.
outXCPotentialMatrix[in]Pointer: Output buffer for computed XC potential matrix. May be NULL.

Returns#

status[out]cuestStatus_t

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.

cuest.bindings.cuestXCPotentialUKSCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupiedAlpha: int, numOccupiedBeta: int, coefficientMatrixAlpha: cuest.bindings.cuest.Pointer, coefficientMatrixBeta: cuest.bindings.cuest.Pointer, outXCEnergy: object, outXCPotentialMatrixAlpha: cuest.bindings.cuest.Pointer, outXCPotentialMatrixBeta: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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

This is the UKS interface that allows the alpha and beta spin densities to be different. The user must provide:

preallocated density matrices (size: nao × nao)
occupied molecular orbitals (size: nocc x nao)
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().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCPotentialUKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]Workspace: Temporary workspace buffer for this operation.
numOccupiedAlpha[in]int: Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta[in]int: Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha[in]Pointer: Input alpha coefficient matrix (size: numOccupiedAlpha × nao) on the GPU. Must not be NULL.
coefficientMatrixBeta[in]Pointer: Input beta coefficient matrix (size: numOccupiedBeta × nao) on the GPU. Must not be NULL.
outXCEnergy[out]Pointer: Output buffer for the computed XC energy (size: 1) on the CPU. Must not be NULL.
outXCPotentialMatrixAlpha[out]Pointer: Output buffer for computed alpha 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]Pointer: Output buffer for computed beta XC potential matrix (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns#

status[out]cuestStatus_t

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 is zero or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCPotentialUKSComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupiedAlpha: int, numOccupiedBeta: int, coefficientMatrixAlpha: cuest.bindings.cuest.Pointer, coefficientMatrixBeta: cuest.bindings.cuest.Pointer, outXCEnergy: object, outXCPotentialMatrixAlpha: cuest.bindings.cuest.Pointer, outXCPotentialMatrixBeta: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required (in bytes) for an UKS 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 density buffers may be NULL.

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCPotentialUKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupiedAlpha[in]int: Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta[in]int: Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha[in]Pointer: Input alpha coefficient matrix. May be NULL.
coefficientMatrixBeta[in]Pointer: Input beta coefficient matrix. May be NULL.
outXCEnergy[in]Pointer: Output buffer for the computed XC energy. May be NULL.
outXCPotentialMatrixAlpha[in]Pointer: Output buffer for computed alpha XC potential matrix. May be NULL.
outXCPotentialMatrixBeta[in]Pointer: Output buffer for computed beta XC potential matrix. May be NULL.

Returns#

status[out]cuestStatus_t

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 is zero or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

XC Derivative#

cuest.bindings.cuestXCDerivativeRKSCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Compute the RKS XC gradient using the supplied XC integral plan, density matrix and occupied molecular orbitals.

This is the RKS interface that assumes the alpha and beta spin densities are identical. The user must provide:

a preallocated density matrix (size: nao × nao)
occupied molecular orbitals (size: nocc x nao)
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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCDerivativeRKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]Workspace: Temporary workspace buffer for this operation.
numOccupied[in]int: Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
outGradient[out]Pointer: Output buffer for computed XC gradient (size: natom × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns#

status[out]cuestStatus_t

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.

cuest.bindings.cuestXCDerivativeRKSComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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 density buffers may be NULL.

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCDerivativeRKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupied[in]int: Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix. May be NULL.
outGradient[in]Pointer: Output buffer for computed XC gradient. May be NULL.

Returns#

status[out]cuestStatus_t

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.

cuest.bindings.cuestXCDerivativeUKSCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupiedAlpha: int, numOccupiedBeta: int, coefficientMatrixAlpha: cuest.bindings.cuest.Pointer, coefficientMatrixBeta: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Compute the UKS XC gradient using the supplied XC integral plan, density matrices and occupied molecular orbitals.

This is the UKS interface that allows the alpha and beta spin densities to be different. The user must provide:

preallocated density matrices (size: nao × nao)
occupied molecular orbitals (size: nocc x nao)
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 cuestXCDerivativeUKSComputeWorkspaceQuery().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCDerivativeUKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]Workspace: Temporary workspace buffer for this operation.
numOccupiedAlpha[in]int: Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta[in]int: Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha[in]Pointer: Input alpha coefficient matrix (size: numOccupiedAlpha × nao) on the GPU. Must not be NULL.
coefficientMatrixBeta[in]Pointer: Input beta coefficient matrix (size: numOccupiedBeta × nao) on the GPU. Must not be NULL.
outGradient[out]Pointer: Output buffer for computed XC gradient (size: natom × 3) on the GPU. Must not be NULL.

Returns#

status[out]cuestStatus_t

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 is zero or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCDerivativeUKSComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupiedAlpha: int, numOccupiedBeta: int, coefficientMatrixAlpha: cuest.bindings.cuest.Pointer, coefficientMatrixBeta: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required (in bytes) for an UKS XC gradient computation. This function returns the workspace needed (host/device) for a single computation, based on the provided plan. Only sizes are computed; output and density buffers may be NULL.

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCDerivativeUKSComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: 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]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupiedAlpha[in]int: Number of alpha occupied orbitals (rows in coefficient matrix); must be greater than zero.
numOccupiedBeta[in]int: Number of beta occupied orbitals (rows in coefficient matrix); must be greater than zero.
coefficientMatrixAlpha[in]Pointer: Input alpha coefficient matrix. May be NULL.
coefficientMatrixBeta[in]Pointer: Input beta coefficient matrix. May be NULL.
outGradient[in]Pointer: Output buffer for computed XC gradient. May be NULL.

Returns#

status[out]cuestStatus_t

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 is zero or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

Advanced XC Functions#

cuest.bindings.cuestXCIntegrationGridCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspace: int, outGridPoints: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Compute the molecular integration grid point coordinates using the provided XC integral plan.

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 user must provide a preallocated output buffer of shape (npoint × 3).

All required temporary workspace must be allocated using the size returned by cuestXCIntegrationGridComputeWorkspaceQuery().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCIntegrationGridComputeParameters: Compute parameters. Must not be NULL.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
outGridPoints[out]Pointer: Output buffer for computed grid point coordinates (size: npoint × 3) on the GPU. Must not be NULL.

Returns#

status[out]CuestStatus

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_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCIntegrationGridComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspaceDescriptor: int, outGridPoints: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required for grid coordinate computation.

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

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCIntegrationGridComputeParameters: Compute parameters. Must not be NULL.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
outGridPoints[in]Pointer: Output buffer for grid point coordinates. May be NULL.

Returns#

status[out]CuestStatus

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_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCIntegrationWeightCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, weightType: cuest.bindings.cuest.CuestXCIntegrationWeightComputeParametersWeightType, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspace: int, outGridWeights: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Compute the 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). All required temporary workspace must be allocated using the size returned by cuestXCIntegrationWeightComputeWorkspaceQuery().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
weightType[in]cuestXCIntegrationWeightComputeParametersWeightType: Weight scheme to compute (total, Becke, quadrature).
parameters[in]cuestXCIntegrationWeightComputeParameters: Compute parameters. Must not be NULL.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
outGridWeights[out]Pointer: Output buffer for integration weights (size: npoint × 1) on the GPU. Must not be NULL.

Returns#

status[out]CuestStatus

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 weightType is unrecognized;
CUEST_STATUS_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCIntegrationWeightComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, weightType: cuest.bindings.cuest.CuestXCIntegrationWeightComputeParametersWeightType, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspaceDescriptor: int, outGridWeights: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required for integration weight computation.

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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
weightType[in]cuestXCIntegrationWeightComputeParametersWeightType: Weight scheme to compute (total, Becke, quadrature).
parameters[in]cuestXCIntegrationWeightComputeParameters: Compute parameters. Must not be NULL.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
outGridWeights[in]Pointer: Output buffer for integration weights. May be NULL.

Returns#

status[out]CuestStatus

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_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCDensityCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outGridDensity: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters[in]cuestXCDensityComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
numOccupied[in]int: Number of occupied orbitals (rows in coefficientMatrix). Must be greater than zero.
coefficientMatrix[in]Pointer: Input orbital coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
outGridDensity[out]Pointer: Output buffer for computed density or density derivatives on the grid (size: npoint × ndim) on the GPU. Must not be NULL.

Returns#

status[out]CuestStatus

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.

cuest.bindings.cuestXCDensityComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, outGridDensity: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters[in]cuestXCDensityComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for temporary workspace sizes. Must not be NULL.
numOccupied[in]int: Number of occupied orbitals (rows in coefficientMatrix). Must be greater than zero.
coefficientMatrix[in]Pointer: Input orbital coefficient matrix. May be NULL.
outGridDensity[in]Pointer: Output buffer for computed density or density derivatives on the grid. May be NULL.

Returns#

status[out]CuestStatus

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.

cuest.bindings.cuestXCPotentialCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, gridXCPotential: cuest.bindings.cuest.Pointer, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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 )\).

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().

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

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters[in]cuestXCPotentialComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
gridXCPotential[in]Pointer: Input XC potential on the grid (size: npoint × ndim) on the GPU. Must not be NULL.
outXCPotentialMatrix[out]Pointer: 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#

status[out]CuestStatus

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.

cuest.bindings.cuestXCPotentialComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, gridXCPotential: cuest.bindings.cuest.Pointer, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required 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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for required temporary workspace sizes. Must not be NULL.
parameters[in]cuestXCPotentialComputeParameters: Compute parameters. Must not be NULL.
gridXCPotential[in]Pointer: Input XC potential on the grid. May be NULL.
outXCPotentialMatrix[in]Pointer: Output buffer for computed XC potential matrix. May be NULL.

Returns#

status[out]CuestStatus

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.

cuest.bindings.cuestXCDerivativeCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspace: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, gridXCPotential: cuest.bindings.cuest.Pointer, outBasisGradient: cuest.bindings.cuest.Pointer, outGridGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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

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().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters[in]cuestXCDerivativeComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
numOccupied[in]uint64_t: Number of occupied orbitals. Must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix (size: numOccupied × nao) on the GPU. Must not be NULL.
gridXCPotential[in]Pointer: Input XC potential on the grid (size: npoint × ndim) on the GPU. Must not be NULL.
outBasisGradient[out]Pointer: Output buffer for computed basis gradient (size: natom × 3) on the GPU. Must not be NULL.
outGridGradient[out]Pointer: Output buffer for computed grid gradient (size: npoint × 3) on the GPU. Must not be NULL.

Returns#

status[out]CuestStatus

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.

cuest.bindings.cuestXCDerivativeComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, approximation: cuest.bindings.cuest.CuestXCAdvancedComputeParametersApproximation, parameters: cuest.bindings.cuest.Parameters, variableBufferSize: int, temporaryWorkspaceDescriptor: int, numOccupied: int, coefficientMatrix: cuest.bindings.cuest.Pointer, gridXCPotential: cuest.bindings.cuest.Pointer, outBasisGradient: cuest.bindings.cuest.Pointer, outGridGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required for an XC energy gradient computation.

This function returns the GPU workspace memory requirements for computing the gradient contributions of the exchange–correlation (XC) energy with respect to the atomic coordinates. Only workspace sizes are computed; input and output pointers may be NULL.

This query must be executed prior to calling cuestXCDerivativeCompute().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
approximation[in]cuestXCAdvancedComputeParametersApproximation: Specifies the XC approximation: LDA, GGA, or meta-GGA.
parameters[in]cuestXCDerivativeComputeParameters: Compute parameters. Must not be NULL.
variableBufferSize[in]WorkspaceDescriptor: User-provided descriptor specifying allowed temporary workspace sizes (host and device). Must not be NULL. 2 GB is a good default maximum workspace for device memory. Host memory is currently unused. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for required temporary workspace sizes. Must not be NULL.
numOccupied[in]uint64_t: Number of occupied orbitals. Must be greater than zero.
coefficientMatrix[in]Pointer: Input coefficient matrix. Must not be NULL.
gridXCPotential[in]Pointer: Input XC potential on the grid. May be NULL.
outBasisGradient[in]Pointer: Output buffer for computed basis gradient. May be NULL.
outGridGradient[in]Pointer: Output buffer for computed grid gradient. May be NULL.

Returns#

status[out]CuestStatus

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.

cuest.bindings.cuestXCGridDerivativeCompute( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspace: int, gridXCEnergy: cuest.bindings.cuest.Pointer, gridGradient: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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}\]

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate().
parameters[in]cuestXCGridDerivativeComputeParameters: Compute parameters. Must not be NULL.
temporaryWorkspace[in]Workspace: Preallocated temporary workspace buffer for this operation. Must not be NULL.
gridXCEnergy[in]Pointer: Input grid XC energy density values (size: npoint × 1) on the GPU. Must not be NULL.
gridGradient[in]Pointer: Input grid spatial gradient contributions (size: npoint × 3) on the GPU. Must not be NULL.
outGradient[out]Pointer: Output total (atomic) gradient of XC energy (size: natom × 3) on the GPU. Must not be NULL.

Returns#

status[out]CuestStatus

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_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestXCGridDerivativeComputeWorkspaceQuery( *, handle: cuest.bindings.cuest.cuestHandle, plan: cuest.bindings.cuest.cuestXCIntPlanHandle, parameters: cuest.bindings.cuest.Parameters, temporaryWorkspaceDescriptor: int, gridXCEnergy: cuest.bindings.cuest.Pointer, gridGradient: cuest.bindings.cuest.Pointer, outGradient: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

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.

This query must be executed prior to calling cuestXCGridDerivativeCompute().

Parameters#

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

Returns#

status[out]CuestStatus

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_EXCEPTION on device or internal error;
CUEST_STATUS_UNKNOWN_ERROR otherwise.