Nonlocal Correlation#

cuest.bindings.cuestNonlocalXCPotentialRKSCompute( *, 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 nonlocal RKS XC potential (Vxc) matrix using the supplied XC integral plan and 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)
a preallocated output buffer (size nao × nao)

The orbital basis and integration grid used are passed via the XCIntPlan. All required temporary workspace must be allocated using the size returned by cuestNonlocalXCPotentialRKSComputeWorkspaceQuery().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlan: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction does not affect this compute routine.
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.
parameters[in]cuestNonlocalXCPotentialRKSComputeParameters: Defines the details of the nonlocal XC functional.
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: Output buffer 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.cuestNonlocalXCPotentialRKSComputeWorkspaceQuery( *, 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 a nonlocal RKS 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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction does not affect this compute routine.
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.
parameters[in]cuestNonlocalXCPotentialRKSComputeParameters: Defines the details of the nonlocal XC functional.
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: Output buffer 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.cuestNonlocalXCPotentialUKSCompute( *, 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, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Compute the nonlocal UKS XC potential (Vxc) matrix using the supplied XC integral plan 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 occupied molecular orbitals (size noccA x nao and noccB 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 cuestNonlocalXCPotentialUKSComputeWorkspaceQuery().

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction does not affect this compute routine.
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.
parameters[in]cuestNonlocalXCPotentialUKSComputeParameters: Defines the details of the nonlocal XC functional.
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.
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 numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestNonlocalXCPotentialUKSComputeWorkspaceQuery( *, 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, outXCPotentialMatrix: cuest.bindings.cuest.Pointer, ) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required (in bytes) for a nonlocal 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 orbital 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(). The cuestXCIntPlanParametersFunctional_t set during plan construction does not affect this compute routine.
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.
parameters[in]cuestNonlocalXCPotentialUKSComputeParameters: Defines the details of the nonlocal XC functional.
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.
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 numOccupiedAlpha or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestNonlocalXCDerivativeRKSCompute( *, 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 derivative of the nonlocal RKS XC energy (Exc) using the supplied XC integral plan and 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)
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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
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.
parameters[in]cuestNonlocalXCDerivativeRKSComputeParameters: Defines the details of the nonlocal XC functional.
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.cuestNonlocalXCDerivativeRKSComputeWorkspaceQuery( *, 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 a nonlocal RKS XC derivative 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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
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.
parameters[in]cuestNonlocalXCDerivativeRKSComputeParameters: Defines the details of the nonlocal XC functional.
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.cuestNonlocalXCDerivativeUKSCompute( *, 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 derivative of the nonlocal UKS XC energy (Exc) using the supplied XC integral plan 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 occupied molecular orbitals (size noccA x nao and noccB x nao)
a preallocated output buffer (size natom × 3)

Parameters#

handle[in]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
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.
parameters[in]cuestNonlocalXCDerivativeUKSComputeParameters: Defines the details of the nonlocal XC functional.
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. 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 or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestNonlocalXCDerivativeUKSComputeWorkspaceQuery( *, 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 a nonlocal UKS XC derivative 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]cuestHandle: cuEST handle. Must not be NULL.
plan[in]cuestXCIntPlanHandle: XC integral plan (opaque handle) constructed with cuestXCIntPlanCreate(). The cuestXCIntPlanParametersFunctional_t set during plan construction determines what XC potential is evaluated.
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.
parameters[in]cuestNonlocalXCDerivativeUKSComputeParameters: Defines the details of the nonlocal XC functional.
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 or numOccupiedBeta is zero;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.