Coulomb#
- cuest.bindings.cuestDFCoulombComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outCoulombMatrix: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a DF Coulomb matrix 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.
Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:
CUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONuses JIT-compiled kernels,CUEST_JIT_USAGE_MODE_OFFuses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE(cuestFfloatUsageMode_t) selects the compute precision:CUEST_FFLOAT_USAGE_MODE_ONrequests ffloat compute,CUEST_FFLOAT_USAGE_MODE_OFFrequests fp64 compute, andCUEST_FFLOAT_USAGE_MODE_DEFAULTrequests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (
CUEST_FFLOAT_USAGE_MODE_ONtogether withCUEST_JIT_USAGE_MODE_OFF) is not supported and returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDFIntPlanHandle
Density-fitted integral plan (opaque handle) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFCoulombComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFCOULOMBCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- densityMatrixPointer
Optional density matrix. May be NULL.
- outCoulombMatrixPointer
Optional output Coulomb 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_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDFCoulombCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDFIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outCoulombMatrix: cuest.bindings.cuest.Pointer,
Compute the AO Coulomb (J) matrix using density fitting (DF) with the supplied DF integral plan and density matrix.
This routine computes the Coulomb matrix (J) from a density matrix using an auxiliary basis and density-fitted integrals. The user must provide a preallocated density matrix (size: nao × nao) and a preallocated output buffer (size: nao × nao). All required temporary workspace must be allocated using the size returned by
cuestDFCoulombComputeWorkspaceQuery().Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:
CUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONuses JIT-compiled kernels,CUEST_JIT_USAGE_MODE_OFFuses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE(cuestFfloatUsageMode_t) selects the compute precision:CUEST_FFLOAT_USAGE_MODE_ONrequests ffloat compute,CUEST_FFLOAT_USAGE_MODE_OFFrequests fp64 compute, andCUEST_FFLOAT_USAGE_MODE_DEFAULTrequests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (
CUEST_FFLOAT_USAGE_MODE_ONtogether withCUEST_JIT_USAGE_MODE_OFF) is not supported and returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDFIntPlanHandle
Density-fitted integral plan (opaque handle) constructed with
cuestDFIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDFCoulombComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFCOULOMBCOMPUTE_PARAMETERS. Must not be NULL.- 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.- densityMatrix[in]Pointer
Input density matrix (size: nao × nao) on the GPU. Must not be NULL.
- outCoulombMatrix[out]Pointer
Output buffer for computed Coulomb 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_PLANif thecuestDFIntPlan_tis not correctly configured or in a dirty state;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outCoulombMatrices: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for a direct 4-center Coulomb (J) matrix computation.
This function returns the workspace needed (host/device) for a single
cuestDirectCoulombCompute()call, based on the provided plan. Only sizes are computed; the density and output buffers may be NULL.Compute parameters. The compilation mode and the integral screening are selected through the compute parameters:
CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD(double): Cauchy-Schwarz screening threshold (>= 0, density-weighted); contributions bounded below the threshold are skipped. A value of 0 disables screening. A negative value returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatricesPointer
Optional density matrices. May be NULL.
- outCoulombMatricesPointer
Optional output Coulomb matrices. 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_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid (negative Schwarz threshold), ifCUEST_JIT_USAGE_MODE_ONis requested with the cuEST CUDA 12 package, or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outCoulombMatrices: cuest.bindings.cuest.Pointer,
Compute AO Coulomb (J) matrices directly from 4-center integrals for a batch of density matrices, with the supplied direct J/K plan.
This routine computes, for each density matrix \(m\) in the batch, the Coulomb matrix
\[J^{(m)}_{pq} = \sum_{rs} (pq|rs) D^{(m)}_{rs}\]exactly (no density fitting), integral-direct from the primary basis. The user must provide
numDensityMatrices(>= 1) preallocated density matrices stored contiguously (size: numDensityMatrices × nao × nao) and a preallocated output buffer laid out the same way (size: numDensityMatrices × nao × nao). All required temporary workspace must be allocated using the size returned bycuestDirectCoulombComputeWorkspaceQuery().The direct J build always uses the full-range 1/r Coulomb operator; the exchange-operator attributes of the plan do not affect it.
This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Compute parameters. The compilation mode and the integral screening are selected through the compute parameters:
CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODE(cuestJITUsageMode_t):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; the default isCUEST_JIT_USAGE_MODE_ONin the cuEST CUDA 13 package andCUEST_JIT_USAGE_MODE_OFFin the cuEST CUDA 12 package. RequestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD(double): Cauchy-Schwarz screening threshold (>= 0, density-weighted); contributions bounded below the threshold are skipped. A value of 0 disables screening. A negative value returnsCUEST_STATUS_INVALID_ARGUMENT.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS. Must not be NULL.- 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.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatrices[in]Pointer
Input density matrices (size: numDensityMatrices × nao × nao, contiguous) on the GPU. Must not be NULL.
- outCoulombMatrices[out]Pointer
Output buffer for the computed Coulomb matrices (size: numDensityMatrices × nao × nao, contiguous) 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_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a parameter value is invalid (negative Schwarz threshold), ifCUEST_JIT_USAGE_MODE_ONis requested with the cuEST CUDA 12 package, or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outCoulombGradients: cuest.bindings.cuest.Pointer,
Query the temporary workspace required for a direct 4-center Coulomb (J) energy gradient computation.
Fills the descriptor with the required temporary sizes for a single
cuestDirectCoulombDerivativeCompute()call.densityMatricesandoutCoulombGradientsmay be NULL (never dereferenced).Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatricesPointer
Optional density matrices. May be NULL.
- outCoulombGradientsPointer
Optional output gradient buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERiftemporaryWorkspaceDescriptoror any other required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices: cuest.bindings.cuest.Pointer,
- outCoulombGradients: cuest.bindings.cuest.Pointer,
Compute the nuclear gradients of the Coulomb energies at fixed density coefficients for a batch of density matrices, directly from 4-center integral derivatives.
For each density matrix \(m\) in the batch this routine computes
\[\nabla_A E_J^{(m)}, \qquad E_J^{(m)} = \sum_{pqrs} D^{(m)}_{pq} (pq|rs) D^{(m)}_{rs} = \sum_{pq} D^{(m)}_{pq} J^{(m)}_{pq}\]as a pure integral-derivative contraction (no density response, no overlap/renormalization terms — the SCF gradient assembles those separately). This is the same energy definition the density-fitted derivative (
cuestDFSymmetricDerivativeCompute(), unitdensityScale) and the Grid-K derivative use, so the three gradients are interchangeable at equal scale. Each output gradient has shape (natom × 3), row-major, one per batch entry in the output buffer (size: numDensityMatrices × natom × 3) on the GPU, and is overwritten. The J derivative, like J itself, always uses the full-range 1/r operator. All required temporary workspace must be allocated using the size returned bycuestDirectCoulombDerivativeComputeWorkspaceQuery().This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Compute parameters. Controlled through the two attributes of this routine’s own
cuestDirectCoulombDerivativeComputeParameters_tobject (CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEandCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- 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.- numDensityMatrices[in]int
Number of density matrices in the batch. Must be >= 1.
- densityMatrices[in]Pointer
Input density matrices (size: numDensityMatrices × nao × nao, contiguous) on the GPU. Must not be NULL.
- outCoulombGradients[out]Pointer
Output buffer (size: numDensityMatrices × natom × 3, contiguous, row-major) 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_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombBilinearDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- numDensityMatrices: int,
- densityMatrices1: cuest.bindings.cuest.Pointer,
- densityMatrices2: cuest.bindings.cuest.Pointer,
- outCoulombGradients: cuest.bindings.cuest.Pointer,
Query the temporary workspace required for a direct 4-center bilinear Coulomb (J) gradient computation.
Fills the descriptor with the required temporary sizes for a single
cuestDirectCoulombBilinearDerivativeCompute()call.densityMatrices1,densityMatrices2andoutCoulombGradientsmay be NULL (never dereferenced).Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Modified in place. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- numDensityMatrices[in]int
Number of density-matrix pairs in the batch. Must be >= 1.
- densityMatrices1Pointer
Optional first density matrices. May be NULL.
- densityMatrices2Pointer
Optional second density matrices (the bilinear form’s D’). May be NULL.
- outCoulombGradientsPointer
Optional output gradient buffer. May be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERiftemporaryWorkspaceDescriptoror any other required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_INVALID_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectCoulombBilinearDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- numDensityMatrices: int,
- densityMatrices1: cuest.bindings.cuest.Pointer,
- densityMatrices2: cuest.bindings.cuest.Pointer,
- outCoulombGradients: cuest.bindings.cuest.Pointer,
Compute the nuclear gradients of the bilinear Coulomb form for a batch of density-matrix pairs.
For each pair (
densityMatrices1[m],densityMatrices2[m]) this routine computes\[\nabla_A E_J^{(m)}, \qquad E_J^{(m)} = \sum_{pqrs} D^{(m)}_{pq} (pq|rs) D'^{(m)}_{rs} = \sum_{pq} D^{(m)}_{pq} J[D'^{(m)}]_{pq}\]as a pure integral-derivative contraction (see
cuestDirectCoulombDerivativeCompute()for the shared conventions). Each output gradient has shape (natom × 3), row-major, one per batch entry in the output buffer (size: numDensityMatrices × natom × 3) on the GPU, and is overwritten. At D’ = D the result equalscuestDirectCoulombDerivativeCompute(). All required temporary workspace must be allocated using the size returned bycuestDirectCoulombBilinearDerivativeComputeWorkspaceQuery().This function is optimized for datacenter GPUs with full-rate FP64; consumer-grade GPUs with reduced FP64 throughput are functional but nonperformant. This API function is only recommended for production use with datacenter GPUs at present time.
Compute parameters. Controlled through the two attributes of this routine’s own
cuestDirectCoulombDerivativeComputeParameters_tobject (CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEandCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD):CUEST_JIT_USAGE_MODE_ONcompiles code specialized to the basis set at first use (a one-time cost per basis set),CUEST_JIT_USAGE_MODE_OFFuses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requestingCUEST_JIT_USAGE_MODE_ONwith the cuEST CUDA 12 package returnsCUEST_STATUS_INVALID_ARGUMENT.Screening. The Schwarz threshold bounds each skipped contribution; a Schwarz threshold of 0 gives an unscreened result.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestDirectIntPlanHandle
Direct J/K plan (opaque handle) constructed with
cuestDirectIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestDirectCoulombDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- 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.- numDensityMatrices[in]int
Number of density-matrix pairs in the batch. Must be >= 1.
- densityMatrices1[in]Pointer
First input density matrices D (size: numDensityMatrices × nao × nao, contiguous) on the GPU. Must not be NULL.
- densityMatrices2[in]Pointer
Second input density matrices D’ (same layout) on the GPU. Must not be NULL.
- outCoulombGradients[out]Pointer
Output buffer (size: numDensityMatrices × natom × 3, contiguous, row-major) 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_PLANif an object the plan views (basis, pair list) has been destroyed;CUEST_STATUS_INVALID_ARGUMENTif a compute attribute is invalid (negative Schwarz threshold, bad JIT mode, or JIT requested with the cuEST CUDA 12 package) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.