Grid-K Integral Plan#

cuest.bindings.cuestGridKIntPlanCreateWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
grid: cuest.bindings.cuest.cuestMolecularGridHandle,
intPlan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
persistentWorkspaceDescriptor: int,
temporaryWorkspaceDescriptor: int,
outPlan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
) → cuest.bindings.cuest.CuestStatus#

Query workspace sizes for creating a grid-based exchange (Grid-K) integral plan.

Simulates all allocations for the Grid-K plan, returning size requirements. No device memory is touched and no plan handle is produced. All handles and required pointers must be valid (not NULL). Output descriptors are filled on success. The arguments must match those passed to the subsequent cuestGridKIntPlanCreate() call, and the same argument validity requirements apply.

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

grid[in]cuestMolecularGridHandle

Molecular integration grid. Constructed with cuestMolecularGridCreate(). Must not be NULL.

intPlan[in]cuestOEIntPlanHandle

One-electron integral plan (opaque handle) constructed with cuestOEIntPlanCreate(). Must not be NULL. Must match the plan passed to the subsequent cuestGridKIntPlanCreate() call.

parameters[in]Parameters

Grid-K plan parameters handle (cuestGridKIntPlanParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_GRIDKINTPLAN_PARAMETERS. Must not be NULL.

variableBufferSize[in]int

User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. Note that the variableBufferSize does not limit total memory usage. There may be static allocations required outside of the scope of what is limited by the variableBufferSize. This value must remain unchanged between WorkspaceQuery and Create calls. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

persistentWorkspaceDescriptor[out]int

Output descriptor for persistent buffers. Must not be NULL. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

temporaryWorkspaceDescriptor[out]int

Output descriptor for temporary buffers. Must not be NULL. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

outPlancuestGridKIntPlanHandle

Unused; accepted for symmetry with cuestGridKIntPlanCreate(). May be NULL.

Returns#

status[out]CuestStatus
cuest.bindings.cuestGridKIntPlanCreate(
*,
handle: cuest.bindings.cuest.cuestHandle,
grid: cuest.bindings.cuest.cuestMolecularGridHandle,
intPlan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
variableBufferSize: int,
persistentWorkspace: int,
temporaryWorkspace: int,
outPlan: cuest.bindings.cuest.cuestGridKIntPlanHandle,
) → cuest.bindings.cuest.CuestStatus#

Build a grid-based exchange (Grid-K) integral plan for atomic orbitals.

The primary basis, atomic coordinates, and AO pair structure are taken from the supplied one-electron integral plan. The plan holds only geometry and grid data, no density-dependent quantities, so a single plan is reusable across all SCF iterations at a fixed molecular geometry. All handles and buffers must be valid. Workspace buffers must be preallocated using sizes from workspace query.

Grid-K forms the AO exchange matrix by numerical quadrature on a molecular grid rather than by analytical evaluation or density fitting:

\[K_{pq} = \sum_{Ars} w^{A} \, X_{p}^{A} \, X_{r}^{A} \, V_{qs}^{A} \, D_{rs}\]

where \(X_{p}^{A} = \phi_{p}(\mathbf{r}_{A})\) is the collocation of AO \(p\) at grid point \(A\), \(w^{A}\) is the Becke quadrature weight of that point, \(D\) is the AO density matrix, and \(V_{qs}^{A}\) is the AO pair potential evaluated at that point:

\[V_{qs}^{A} = \int \phi_{q}(\mathbf{r}) \, V(|\mathbf{r} - \mathbf{r}_{A}|) \, \phi_{s}(\mathbf{r}) \, d\mathbf{r}\]

The cuestGridKIntPlan_t may be configured to treat range-separated exchange operators, using the same parameterization as the density-fitted integral plan.

\[\underbrace{\frac{1}{r}}_{\text{full-range}} = \underbrace{\frac{\mathrm{erfc}(\omega r)}{r}}_{\text{short-range}} + \underbrace{\frac{\mathrm{erf}(\omega r)}{r}}_{\text{long-range}}\]

In cuEST, range-separation is parameterized in terms of the full-range and long-range components.

The operator \(V\) entering \(V_{qs}^{A}\) above is therefore

\[V(r) = f_{\rm HF} \, \frac{1}{r} + f_{\rm LRC} \, \frac{{\rm erf}(\omega r)}{r}\]

where \(f_{\rm HF}\) is the fraction of Hartree-Fock exchange to add (CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION), \(f_{\rm LRC}\) is the fraction of the long-range component of range-separated exchange to add (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION), and \(\omega\) is the range-separation parameter (CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA).

It is required that the operator specification respect the following conditions:

CUEST_STATUS_INVALID_ARGUMENT will be returned if these conditions are not respected during handle creation.

The operator specification is fixed at creation and is respected by all subsequent calls involving the cuestGridKIntPlan_t. The fractions and \(\omega\) have exactly the same meaning as for the cuestDFIntPlan_t, so the example configurations given for cuestDFIntPlanCreate() (PBE0, \(\omega\)B97, \(\omega\)B97M-V, HSE06) carry over unchanged.

Accuracy and cost of the plan are additionally controlled by CUEST_GRIDKINTPLAN_PARAMETERS_THRESHOLD_COLLOCATION, the threshold below which an AO is treated as negligible over a block of grid points and sieved out of the collocation structures. Larger values produce smaller, faster collocation structures at the cost of accuracy in every subsequent Grid-K compute call.

Note

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

grid[in]cuestMolecularGridHandle

Molecular integration grid. Constructed with cuestMolecularGridCreate(). Must not be NULL.

intPlan[in]cuestOEIntPlanHandle

One-electron integral plan (opaque handle) constructed with cuestOEIntPlanCreate() over the primary basis. Must not be NULL. The Grid-K plan takes its basis, atomic coordinates, and AO pair structure from it, and it must not be destroyed until after the final call to any Grid-K compute routines.

parameters[in]Parameters

Grid-K plan parameters handle (cuestGridKIntPlanParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_GRIDKINTPLAN_PARAMETERS; holds the operator specification and collocation threshold. Must not be NULL. Must not be NULL.

variableBufferSize[in]int

User-provided descriptor for an internal scratch buffer (host and device). Must not be NULL. Note that the variableBufferSize does not limit total memory usage. There may be static allocations required outside of the scope of what is limited by the variableBufferSize. This value must remain unchanged between WorkspaceQuery and Create calls. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

persistentWorkspace[in]int

Workspace for persistent buffers; holds the plan’s data for the lifetime of the plan. Must not be NULL. Integer address of a cuestWorkspace_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in cuda_utils.py.

temporaryWorkspace[in]int

Workspace for temporary buffers used during construction. Must not be NULL. Integer address of a cuestWorkspace_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in cuda_utils.py.

outPlan[out]cuestGridKIntPlanHandle

Output pointer for the Grid-K plan handle. Must not be NULL.

Returns#

status[out]CuestStatus
cuest.bindings.cuestGridKIntPlanDestroy(
*,
handle: cuest.bindings.cuest.cuestGridKIntPlanHandle,
) → cuest.bindings.cuest.CuestStatus#

Destroy/free a grid-based exchange (Grid-K) integral plan and all resources.

The plan handle and its memory must not be used after destruction. The persistent workspace supplied to cuestGridKIntPlanCreate() may be released by the user once the plan has been destroyed.

Parameters#

handle[in]cuestGridKIntPlanHandle

Grid-K plan handle to destroy. Must not be NULL.

Returns#

status[out]CuestStatus