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,
Compute the 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:
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 bycuestXCPotentialRKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the potential assembly, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the potential assembly. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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]data_double
Output
data_doublewhosevaluereceives the computed XC energy 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALRKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
- coefficientMatrixPointer
Input coefficient matrix. May be NULL.
- outXCEnergydata_double
data_doublefor the computed XC energy; not written by the workspace query. May be NULL.- outXCPotentialMatrixPointer
Output buffer for computed XC potential matrix. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
Compute the 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:
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 bycuestXCPotentialUKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the potential assembly, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the potential assembly. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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]data_double
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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedAlphais zero ornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALUKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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.
- coefficientMatrixAlphaPointer
Input alpha coefficient matrix. May be NULL.
- coefficientMatrixBetaPointer
Input beta coefficient matrix. May be NULL.
- outXCEnergydata_double
Output buffer for the computed XC energy. May be NULL.
- outXCPotentialMatrixAlphaPointer
Output buffer for computed alpha XC potential matrix. May be NULL.
- outXCPotentialMatrixBetaPointer
Output buffer for computed beta XC potential matrix. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedAlphais zero ornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
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,
Compute the RKS XC gradient 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:
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 bycuestXCDerivativeRKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the gradient collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the gradient collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVERKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals (rows in coefficient matrix); must be greater than zero.
- coefficientMatrixPointer
Input coefficient matrix. May be NULL.
- outGradientPointer
Output buffer for computed XC gradient. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
Compute the UKS XC gradient 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:
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 bycuestXCDerivativeUKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the gradient collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the gradient collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedAlphais zero ornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVEUKSCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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.
- coefficientMatrixAlphaPointer
Input alpha coefficient matrix. May be NULL.
- coefficientMatrixBetaPointer
Input beta coefficient matrix. May be NULL.
- outGradientPointer
Output buffer for computed XC gradient. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedAlphais zero ornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONif the plan’s functional isCUEST_XCINTPLAN_PARAMETERS_FUNCTIONAL_HF;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCIntegrationGridComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCINTEGRATIONGRIDCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCIntegrationGridComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCINTEGRATIONGRIDCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outGridPointsPointer
Output buffer for grid point coordinates. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCIntegrationWeightCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- weightType: int,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- outGridWeights: cuest.bindings.cuest.Pointer,
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 bycuestXCIntegrationWeightComputeWorkspaceQuery().Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- weightType[in]CuestXCIntegrationWeightComputeParametersWeightType
Weight scheme to compute (total, Becke, quadrature). Python enum mirroring the C API type
cuestXCIntegrationWeightComputeParametersWeightType_t(CUEST_XCINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_TOTAL/_BECKE/_QUADRATURE).- parameters[in]Parameters
Compute parameters handle (
cuestXCIntegrationWeightComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCINTEGRATIONWEIGHTCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- outGridWeights[out]Pointer
Output buffer for integration weights (size: npoint × 1) on the GPU. Must not be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifweightTypeis unrecognized;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCIntegrationWeightComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- weightType: int,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- outGridWeights: cuest.bindings.cuest.Pointer,
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(). Must not be NULL.- weightType[in]CuestXCIntegrationWeightComputeParametersWeightType
Weight scheme to compute (total, Becke, quadrature). Python enum mirroring the C API type
cuestXCIntegrationWeightComputeParametersWeightType_t(CUEST_XCINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_TOTAL/_BECKE/_QUADRATURE).- parameters[in]Parameters
Compute parameters handle (
cuestXCIntegrationWeightComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCINTEGRATIONWEIGHTCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outGridWeightsPointer
Output buffer for integration weights. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_ARGUMENTifweightTypeis unrecognized;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCDensityCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numOccupied: int,
- coefficientMatrix: cuest.bindings.cuest.Pointer,
- outGridDensity: cuest.bindings.cuest.Pointer,
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 not 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.Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCDENSITYCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDENSITYCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCDensityComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDENSITYCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCDensityComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numOccupied: int,
- coefficientMatrix: cuest.bindings.cuest.Pointer,
- outGridDensity: cuest.bindings.cuest.Pointer,
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(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCDensityComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDENSITYCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals (rows in
coefficientMatrix). Must be greater than zero.- coefficientMatrixPointer
Input orbital coefficient matrix. May be NULL.
- outGridDensityPointer
Output buffer for computed density or density derivatives on the grid. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCNonsymmetricDensityCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numOccupied: int,
- leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrix: cuest.bindings.cuest.Pointer,
- outGridDensity: cuest.bindings.cuest.Pointer,
Compute the nonsymmetric electron density on the integration grid using two sets of molecular orbitals.
This routine evaluates the nonsymmetric electronic density (and its derivatives, when applicable) on the molecular integration grid. The nonsymmetric density is formed from a left and a right set of occupied molecular orbitals, both of size numOccupied × nao. This is the generalization of
cuestXCDensityCompute(), which uses the same coefficients for both left and right.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 )\).
All required workspace must first be allocated according to the size returned by
cuestXCNonsymmetricDensityComputeWorkspaceQuery(), which must be called before invoking this function.Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCNONSYMMETRICDENSITYCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the density collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCNONSYMMETRICDENSITYCOMPUTE_PARAMETERS_DETAIL_DENSITY_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the density collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCNonsymmetricDensityComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCNONSYMMETRICDENSITYCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals (rows in each coefficient matrix). Must be greater than zero.
- leftCoefficientMatrix[in]Pointer
Input left orbital coefficient matrix (size:
numOccupied× nao) on the GPU. Must not be NULL.- rightCoefficientMatrix[in]Pointer
Input right orbital coefficient matrix (size:
numOccupied× nao) on the GPU. Must not be NULL.- outGridDensity[out]Pointer
Output buffer for computed nonsymmetric density or density derivatives on the grid (size: npoint × ndim) on the GPU. Must not be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCNonsymmetricDensityComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numOccupied: int,
- leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrix: cuest.bindings.cuest.Pointer,
- outGridDensity: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for an XC nonsymmetric density computation.
Determines the GPU memory requirements for computing the nonsymmetric electron density (and its derivatives) on the molecular grid. Only memory requirements are estimated; no actual computation is performed. Input and output pointers may be NULL.
This call must precede
cuestXCNonsymmetricDensityCompute()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(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCNonsymmetricDensityComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCNONSYMMETRICDENSITYCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals (rows in each coefficient matrix). Must be greater than zero.
- leftCoefficientMatrixPointer
Input left orbital coefficient matrix. May be NULL.
- rightCoefficientMatrixPointer
Input right orbital coefficient matrix. May be NULL.
- outGridDensityPointer
Output buffer for computed nonsymmetric density or density derivatives on the grid. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCPotentialCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- gridXCPotential: cuest.bindings.cuest.Pointer,
- outXCPotentialMatrix: cuest.bindings.cuest.Pointer,
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) containing the XC potential components (derivatives of the XC energy density \(f\)) ordered as:
LDA: ndim = 1 \(( \partial f / \partial\rho )\);
GGA: ndim = 4 \(( \partial f / \partial\rho,\; 4 (\partial f / \partial\gamma) \nabla_{x}\rho,\; 4 (\partial f / \partial\gamma) \nabla_{y}\rho,\; 4 (\partial f / \partial\gamma) \nabla_{z}\rho )\), where \(\gamma = |\nabla\rho|^{2}\);
meta-GGA: ndim = 5 (the GGA components followed by \(\partial f / \partial\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().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCPOTENTIALCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the potential assembly, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCPOTENTIALCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the potential assembly. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCPotentialComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- gridXCPotential: cuest.bindings.cuest.Pointer,
- outXCPotentialMatrix: cuest.bindings.cuest.Pointer,
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(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCPotentialComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCPOTENTIALCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for required temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- gridXCPotentialPointer
Input XC potential on the grid. May be NULL.
- outXCPotentialMatrixPointer
Output buffer for computed XC potential matrix. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- 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,
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
gridXCPotentialdepend on the chosen approximation type (LDA, GGA, or meta-GGA) – seecuestXCPotentialCompute(). All temporary workspace must be preallocated according to the size returned bycuestXCDerivativeComputeWorkspaceQuery().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().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the gradient collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the gradient collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numOccupied[in]int
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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- 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,
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(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for required temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals. Must be greater than zero.
- coefficientMatrix[in]Pointer
Input coefficient matrix. Must not be NULL.
- gridXCPotentialPointer
Input XC potential on the grid. May be NULL.
- outBasisGradientPointer
Output buffer for computed basis gradient. May be NULL.
- outGridGradientPointer
Output buffer for computed grid gradient. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCNonsymmetricDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- numOccupied: int,
- leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrix: cuest.bindings.cuest.Pointer,
- gridXCPotential: cuest.bindings.cuest.Pointer,
- outBasisGradient: cuest.bindings.cuest.Pointer,
- outGridGradient: cuest.bindings.cuest.Pointer,
Compute the nonsymmetric XC energy gradient contributions from a grid XC potential.
This routine computes the gradient contributions of the XC energy with respect to atomic coordinates using a nonsymmetric density. It uses the provided XC potential on the molecular integration grid, a left and a right set of molecular orbital coefficients, and the XC integral plan. This is the generalization of
cuestXCDerivativeCompute(), which uses the same coefficients for both left and right.The form and dimensionality of the input
gridXCPotentialdepend on the chosen approximation type (LDA, GGA, or meta-GGA) – seecuestXCPotentialCompute(). All temporary workspace must be preallocated according to the size returned bycuestXCNonsymmetricDerivativeComputeWorkspaceQuery().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().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_XCNONSYMMETRICDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the gradient collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_XCNONSYMMETRICDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the gradient collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCNonsymmetricDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCNONSYMMETRICDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals in each coefficient matrix. Must be greater than zero.
- leftCoefficientMatrix[in]Pointer
Input left orbital coefficient matrix (size:
numOccupied× nao) on the GPU. Must not be NULL.- rightCoefficientMatrix[in]Pointer
Input right orbital 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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestXCNonsymmetricDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestXCIntPlanHandle,
- approximation: int,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- numOccupied: int,
- leftCoefficientMatrix: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrix: cuest.bindings.cuest.Pointer,
- gridXCPotential: cuest.bindings.cuest.Pointer,
- outBasisGradient: cuest.bindings.cuest.Pointer,
- outGridGradient: cuest.bindings.cuest.Pointer,
Query the temporary workspace required for an XC nonsymmetric derivative computation.
This function returns the GPU workspace memory requirements for computing the nonsymmetric XC energy gradient contributions. Only workspace sizes are computed; input and output pointers may be NULL.
This query must be executed prior to calling
cuestXCNonsymmetricDerivativeCompute().Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestXCIntPlanHandle
XC integral plan (opaque handle) constructed with
cuestXCIntPlanCreate(). Must not be NULL.- approximation[in]CuestXCAdvancedComputeParametersApproximation
Specifies the XC approximation: LDA, GGA, or meta-GGA. Python enum mirroring the C API type
cuestXCAdvancedComputeParametersApproximation_t(CUEST_XCADVANCED_PARAMETERS_APPROXIMATION_LDA/_GGA/_METAGGA).- parameters[in]Parameters
Compute parameters handle (
cuestXCNonsymmetricDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCNONSYMMETRICDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
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. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for required temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numOccupied[in]int
Number of occupied orbitals. Must be greater than zero.
- leftCoefficientMatrixPointer
Input left coefficient matrix. May be NULL.
- rightCoefficientMatrixPointer
Input right coefficient matrix. May be NULL.
- gridXCPotentialPointer
Input XC potential on the grid. May be NULL.
- outBasisGradientPointer
Output buffer for computed basis gradient. May be NULL.
- outGridGradientPointer
Output buffer for computed grid gradient. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_INVALID_ARGUMENTifnumOccupiedis zero orapproximationis invalid, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
Compute the integration-weight and grid-motion contributions to the 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 integration-weight and grid-motion contributions to the XC gradient with respect to atomic coordinates. The sum of
outGradientcomputed by this routine and theoutBasisGradientcomputed bycuestXCDerivativeCompute()(scaled appropriately) is the derivative of the XC energy. 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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCGridDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCGRIDDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Preallocated temporary workspace buffer for this operation. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- 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 integration-weight and grid-motion contributions to the XC gradient (size: natom × 3) on the GPU. Must not be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestXCGridDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_XCGRIDDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor with required temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- gridXCEnergyPointer
Input grid XC energy density. May be NULL.
- gridGradientPointer
Input grid gradient contributions. May be NULL.
- outGradientPointer
Output gradient contribution array. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are of incorrect type;CUEST_STATUS_EXCEPTIONon device or internal error;CUEST_STATUS_UNKNOWN_ERRORotherwise.