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,
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 subsequentcuestGridKIntPlanCreate()call.- parameters[in]Parameters
Grid-K plan parameters handle (
cuestGridKIntPlanParameters()) initialized bycuestParametersCreate()withCuestParametersType.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_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- persistentWorkspaceDescriptor[out]int
Output descriptor for persistent buffers. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary buffers. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outPlancuestGridKIntPlanHandle
Unused; accepted for symmetry with
cuestGridKIntPlanCreate(). 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_ARGUMENTif any of thecuestGridKIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifintPlanwas constructed with functions that exceed L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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,
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_tmay 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.
CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION: Controls the fraction of full-range exchange included.CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION: Controls the fraction of long-range exchange included.CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA: Specifies the range separation parameter.
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_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION+CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION\(\ge 0\).CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA\(\ge 0\). This is checked, and the value used, only whenCUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONis nonzero.
CUEST_STATUS_INVALID_ARGUMENTwill 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 thecuestDFIntPlan_t, so the example configurations given forcuestDFIntPlanCreate()(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
The number of atoms in the primary basis of the
cuestOEIntPlan_tplan handle must match the number of atoms in thecuestMolecularGrid_tgrid handle.It is the user’s responsibility not to destroy the
cuestOEIntPlan_tplan handle orcuestMolecularGrid_tgrid handle until operations involving thecuestGridKIntPlan_tplan handle are complete.After the
cuestOEIntPlan_tplan handle orcuestMolecularGrid_tgrid handle are destroyed, thecuestGridKIntPlan_tplan handle is no longer valid, and compute calls using it returnCUEST_STATUS_INVALID_PLAN.Screening of negligible AO pairs used while building and using this
cuestGridKIntPlan_tplan handle is controlled bythresholdPQset during construction of thecuestAOPairList_tpair list handle provided tocuestOEIntPlanCreate(). This is separate from the collocation threshold described above.
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 bycuestParametersCreate()withCuestParametersType.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_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin 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_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- temporaryWorkspace[in]int
Workspace for temporary buffers used during construction. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- outPlan[out]cuestGridKIntPlanHandle
Output pointer for the Grid-K plan handle. Must not 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_ARGUMENTif any of thecuestGridKIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifintPlanwas constructed with functions that exceed L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestGridKIntPlanDestroy(
- *,
- handle: cuest.bindings.cuest.cuestGridKIntPlanHandle,
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
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_NULL_POINTERif the plan handle is NULL;CUEST_STATUS_INVALID_TYPEif the plan handle is not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.