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,
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
plan. All required temporary workspace must be allocated using the size returned bycuestNonlocalXCPotentialRKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_NONLOCALXCPOTENTIALRKSCOMPUTE_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_NONLOCALXCPOTENTIALRKSCOMPUTE_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_NONLOCALXCPOTENTIALRKSCOMPUTE_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_NONLOCALXCPOTENTIALRKSCOMPUTE_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. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCPotentialRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCPOTENTIALRKSCOMPUTE_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 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
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_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCPotentialRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCPOTENTIALRKSCOMPUTE_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
Output buffer for the computed XC energy. 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_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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 bycuestNonlocalXCPotentialUKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_NONLOCALXCPOTENTIALUKSCOMPUTE_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_NONLOCALXCPOTENTIALUKSCOMPUTE_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_NONLOCALXCPOTENTIALUKSCOMPUTE_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_NONLOCALXCPOTENTIALUKSCOMPUTE_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. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCPotentialUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCPOTENTIALUKSCOMPUTE_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.
- 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_ARGUMENTifnumOccupiedAlphaornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCPotentialUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCPOTENTIALUKSCOMPUTE_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.
- 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_ARGUMENTifnumOccupiedAlphaornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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 bycuestNonlocalXCDerivativeRKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_NONLOCALXCDERIVATIVERKSCOMPUTE_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_NONLOCALXCDERIVATIVERKSCOMPUTE_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_NONLOCALXCDERIVATIVERKSCOMPUTE_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_NONLOCALXCDERIVATIVERKSCOMPUTE_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. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCDerivativeRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCDERIVATIVERKSCOMPUTE_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_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCDerivativeRKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCDERIVATIVERKSCOMPUTE_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_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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)
The orbital basis and integration grid used are passed via the
plan. All required temporary workspace must be allocated using the size returned bycuestNonlocalXCDerivativeUKSComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_NONLOCALXCDERIVATIVEUKSCOMPUTE_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_NONLOCALXCDERIVATIVEUKSCOMPUTE_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_NONLOCALXCDERIVATIVEUKSCOMPUTE_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_NONLOCALXCDERIVATIVEUKSCOMPUTE_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. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCDerivativeUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCDERIVATIVEUKSCOMPUTE_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. 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_ARGUMENTifnumOccupiedAlphaornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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(). Must not be NULL. ThecuestXCIntPlanParametersFunctional_tset during plan construction does not affect this compute routine.- parameters[in]Parameters
Defines the details of the nonlocal XC functional. Parameters handle (
cuestNonlocalXCDerivativeUKSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_NONLOCALXCDERIVATIVEUKSCOMPUTE_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_ARGUMENTifnumOccupiedAlphaornumOccupiedBetais zero, or if a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.