Coulomb#
- group Coulomb
Functions
- cuestStatus_t cuestDFCoulombCompute(
- cuestHandle_t handle,
- const cuestDFIntPlan_t plan,
- const cuestDFCoulombComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- const double *densityMatrix,
- double *outCoulombMatrix
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), a
cuestDFIntPlan_t, and a preallocated output buffer (size: nao × nao). All required temporary workspace must be allocated using the size returned bycuestDFCoulombComputeWorkspaceQuery.The supplied plan may be constructed either with cached (precomputed) 3-center integrals or in integral-direct mode (
CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTset to a non-zero value). Both configurations are supported: an integral-direct plan stores no fitted 3-index tensor and instead recomputes the required 3-center integrals on the fly.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] cuEST handle. Must not be NULL.
plan – [in] Density-fitted integral plan (opaque handle) constructed with
cuestDFIntPlanCreate. Must not be NULL.parameters – [in] Compute parameters (
cuestDFCoulombComputeParameters_t). Must not be NULLCreate with
cuestParametersCreate()usingCUEST_DFCOULOMBCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_tParameter to control the use of ffloat compute.
Default:
CUEST_FFLOAT_USAGE_MODE_DEFAULTCUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwise
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
densityMatrix – [in] Input density matrix (size: nao × nao) on GPU. Must not be NULL.
outCoulombMatrix – [out] Output buffer for computed Coulomb matrix (size: nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
- Returns:
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.
- cuestStatus_t cuestDFCoulombComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDFIntPlan_t plan,
- const cuestDFCoulombComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- const double *densityMatrix,
- double *outCoulombMatrix
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
cuestDFIntPlan_t. Only sizes are computed; output and density buffers may be NULL.As with
cuestDFCoulombCompute, the plan may be constructed either with cached (precomputed) 3-center integrals or in integral-direct mode (CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTset to a non-zero value); both configurations are supported and are reflected in the returned workspace sizes.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] cuEST handle. Must not be NULL.
plan – [in] Density-fitted integral plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestDFCoulombComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DFCOULOMBCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DFCOULOMBCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_tParameter to control the use of ffloat compute.
Default:
CUEST_FFLOAT_USAGE_MODE_DEFAULTCUEST_DFCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwise
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
densityMatrix – Optional density matrix (may be NULL).
outCoulombMatrix – Optional output Coulomb matrix (may be NULL).
- Returns:
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.
- group DirectCoulomb
Functions
- cuestStatus_t cuestDirectCoulombCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outCoulombMatrices
Compute AO Coulomb (J) matrices directly from 4-center integrals for a batch of density matrices.
Computes, for each density matrix m in the batch,
\[ J^{(m)}_{pq} = \sum_{rs} (pq|rs) D^{(m)}_{rs} \]exactly (no density fitting), integral-direct from the primary basis.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.
On failure the contents of
outCoulombMatricesare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle) constructed with
cuestDirectIntPlanCreate. Must not be NULL.parameters – [in] Compute parameters (
cuestDirectCoulombComputeParameters_t; attributes in cuestDirectCoulombComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation (size from
cuestDirectCoulombComputeWorkspaceQuery). Must not be NULL.numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices (size: numDensityMatrices × nao × nao, contiguous) on GPU. Must not be NULL.
outCoulombMatrices – [out] Output buffer (size: numDensityMatrices × nao × nao, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectCoulombComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outCoulombMatrices
Workspace query for
cuestDirectCoulombCompute.Fills the descriptor with the sizes required by a single
cuestDirectCoulombComputecall, based on the provided plan and compute parameters. Only sizes are computed;densityMatricesandoutCoulombMatricesmay be NULL.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices. May be NULL.
outCoulombMatrices – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectCoulombDerivativeCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombDerivativeComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outCoulombGradients
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 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). Each output gradient has shape (natom, 3), row-major, one per batch entry, and is overwritten. The J derivative, like J itself, always uses the full-range operator. 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.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.
On failure the contents of
outCoulombGradientsare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestDirectCoulombDerivativeComputeParameters_t; attributes in cuestDirectCoulombDerivativeComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices (size: numDensityMatrices × nao × nao, contiguous) on GPU. Must not be NULL.
outCoulombGradients – [out] Output buffer (size: numDensityMatrices × natom × 3, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectCoulombDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombDerivativeComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices,
- double *outCoulombGradients
Workspace query for
cuestDirectCoulombDerivativeCompute.Fills the descriptor with the temporary workspace sizes required by
cuestDirectCoulombDerivativeCompute.densityMatricesandoutCoulombGradientsmay be NULL (never dereferenced).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density matrices in the batch. Must be >= 1.
densityMatrices – [in] Input density matrices. May be NULL.
outCoulombGradients – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectCoulombBilinearDerivativeCompute(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombDerivativeComputeParameters_t parameters,
- cuestWorkspace_t *temporaryWorkspace,
- uint64_t numDensityMatrices,
- const double *densityMatrices1,
- const double *densityMatrices2,
- double *outCoulombGradients
Compute the nuclear gradients of the bilinear Coulomb form at fixed density coefficients for a batch of density-matrix pairs, directly from 4-center integral derivatives.
For each pair (D, D’) = (
densityMatrices1[m],densityMatrices2[m]) this 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; seecuestDirectCoulombDerivativeComputefor the shared conventions. Each output gradient has shape (natom, 3), row-major, one per pair, and is overwritten. At D’ = D the result equalscuestDirectCoulombDerivativeCompute(the Coulomb-energy gradient). The Schwarz threshold ofparametersbounds each skipped contribution; a Schwarz threshold of 0 gives an unscreened result.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.
On failure the contents of
outCoulombGradientsare undefined (earlier batch entries may already have been written).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters (
cuestDirectCoulombDerivativeComputeParameters_t; attributes in cuestDirectCoulombDerivativeComputeParametersAttributes_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.
numDensityMatrices – [in] Number of density-matrix pairs in the batch. Must be >= 1.
densityMatrices1 – [in] First density matrices D (size: numDensityMatrices × nao × nao, contiguous) on GPU. Must not be NULL.
densityMatrices2 – [in] Second density matrices D’ (same layout) on GPU. Must not be NULL.
outCoulombGradients – [out] Output buffer (size: numDensityMatrices × natom × 3, contiguous) on GPU; overwritten. Must not be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestDirectCoulombBilinearDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestDirectIntPlan_t plan,
- const cuestDirectCoulombDerivativeComputeParameters_t parameters,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- uint64_t numDensityMatrices,
- const double *densityMatrices1,
- const double *densityMatrices2,
- double *outCoulombGradients
Workspace query for
cuestDirectCoulombBilinearDerivativeCompute.Fills the descriptor with the temporary workspace sizes required by
cuestDirectCoulombBilinearDerivativeCompute.densityMatrices1,densityMatrices2andoutCoulombGradientsmay be NULL (never dereferenced).- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] Direct plan (opaque handle). Must not be NULL.
parameters – [in] Compute parameters. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_tParameter to control the use of JIT-compiled kernels.
Default:
CUEST_JIT_USAGE_MODE_ONon CUDA 13.x+,CUEST_JIT_USAGE_MODE_OFFotherwiseCUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLDdoubleDensity-weighted Cauchy-Schwarz screening threshold (>= 0; 0 disables screening).
Default:
1.0e-13
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
numDensityMatrices – [in] Number of density-matrix pairs in the batch. Must be >= 1.
densityMatrices1 – [in] First density matrices. May be NULL.
densityMatrices2 – [in] Second density matrices. May be NULL.
outCoulombGradients – [out] Output buffer. May be NULL.
- Returns:
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, JIT requested on an unsupported toolkit) or ifnumDensityMatricesis 0;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.