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,
) → cuest.bindings.cuest.CuestStatus#

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:

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

densityMatrixPointer

Optional density matrix. May be NULL.

outCoulombMatrixPointer

Optional output Coulomb matrix. May be NULL.

Returns#

status[out]CuestStatus
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,
) → cuest.bindings.cuest.CuestStatus#

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:

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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:

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestDirectCoulombComputeWorkspaceQuery().

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:

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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. densityMatrices and outCoulombGradients may 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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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(), unit densityScale) 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 by cuestDirectCoulombDerivativeComputeWorkspaceQuery().

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_t object (CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE and CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD): CUEST_JIT_USAGE_MODE_ON compiles code specialized to the basis set at first use (a one-time cost per basis set), CUEST_JIT_USAGE_MODE_OFF uses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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, densityMatrices2 and outCoulombGradients may 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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 equals cuestDirectCoulombDerivativeCompute(). All required temporary workspace must be allocated using the size returned by cuestDirectCoulombBilinearDerivativeComputeWorkspaceQuery().

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_t object (CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE and CUEST_DIRECTCOULOMBDERIVATIVECOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD): CUEST_JIT_USAGE_MODE_ON compiles code specialized to the basis set at first use (a one-time cost per basis set), CUEST_JIT_USAGE_MODE_OFF uses the precompiled path. Just-in-time compilation is only available in the cuEST CUDA 13 package; requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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