Grid-K Integral Plan#
- group GridKIntegralPlan
Functions
- cuestStatus_t cuestGridKIntPlanCreate(
- cuestHandle_t handle,
- const cuestMolecularGrid_t grid,
- const cuestOEIntPlan_t intPlan,
- const cuestGridKIntPlanParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *persistentWorkspace,
- cuestWorkspace_t *temporaryWorkspace,
- cuestGridKIntPlan_t *outPlan
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.
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.
It is required that the operator specification respect the following conditions:
CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTION\(\ge 0\).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 thecuestGridKIntPlan_t.The
cuestGridKIntPlan_tmay optionally be configured to fit the collocation, reducing the quadrature error of the grid:CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM:WithCUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRICthe collocation is dressed, \( \bar{X} = M X \), such that the quadrature reproduces the analytic overlap matrix on the retained subspace, \( \bar{X} W \bar{X}^{T} = S \). The default (CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_NONE) uses the raw collocation.CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFF:Absolute cutoff on the eigenvalues of \( S \) (canonical orthogonalization). Must be \( > 0 \).CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_CUTOFF:Absolute cutoff on the eigenvalues of the fitting metric \( \Omega \) (the quadrature overlap in the orthonormalized basis, unity for an exact grid). Must be in \( (0, 1) \).
The transfer matrix \( M \) is built at plan creation from the overlap matrix of
intPlanand held for the lifetime of the plan. Diagnostics of the fit may be queried from the created plan viacuestQuery; seecuestGridKIntPlanAttributes_t.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
grid – [in] Molecular integration grid. Must not be NULL.
intPlan – [in] One-electron integral plan handle of type
cuestOEIntPlan_t. The one-electron integral plan should be created withcuestOEIntPlanCreateover the primary basis; 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. Must not be NULL.parameters – [in] Grid-K plan parameters structure (operator specification and collocation threshold). Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_GRIDKINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().7 configurable attributes
CUEST_GRIDKINTPLAN_PARAMETERS_THRESHOLD_COLLOCATIONdoubleAO collocation threshold.
Default:
1.0e-18CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of full-range (1/r) exchange.
Default:
1.0CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range (erf(wr)/r) exchange.
Default:
0.0CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega range-separation parameter (in inverse bohr). Must be >= 0.0.
Default:
0.0CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestGridKIntPlanParametersFittingAlgorithm_tAlgorithm used to fit the collocation of the grid-based exchange.
Default:
CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_NONECUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFFdoubleAbsolute overlap eigenvalue cutoff for the canonical orthogonalization underlying the fit. Must be > 0.0.
Default:
1.0e-6CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_CUTOFFdoubleAbsolute cutoff on the eigenvalues of the orthonormalized quadrature overlap (dimensionless recovered-norm fractions, unity for an exact grid); directions below the cutoff (including any with negative quadrature weight content) are excluded from the fit. Must be in (0.0, 1.0).
Default:
1.0e-2
variableBufferSize – [in] 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.
persistentWorkspace – [in] Workspace for persistent buffers; holds the plan’s data for the lifetime of the plan. Must not be NULL.
temporaryWorkspace – [in] Workspace for temporary buffers used during construction. Must not be NULL.
outPlan – [out] Output pointer for the Grid-K plan handle. 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_ARGUMENTif any of thecuestGridKIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifintPlanwas constructed with functions that exceed L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuestStatus_t cuestGridKIntPlanCreateWorkspaceQuery(
- cuestHandle_t handle,
- const cuestMolecularGrid_t grid,
- const cuestOEIntPlan_t intPlan,
- const cuestGridKIntPlanParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- cuestGridKIntPlan_t *outPlan
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
cuestGridKIntPlanCreatecall, and the same argument validity requirements apply.- Since
v0.3.0
- Parameters:
handle – [in] cuEST handle. Must not be NULL.
grid – [in] Molecular integration grid. Must not be NULL.
intPlan – [in] One-electron integral plan handle of type
cuestOEIntPlan_t. The one-electron integral plan should be created withcuestOEIntPlanCreateand must match the plan passed to the subsequentcuestGridKIntPlanCreatecall. Must not be NULL.parameters – [in] Grid-K plan parameters structure. Must not be NULL.
Create with
cuestParametersCreate()usingCUEST_GRIDKINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().7 configurable attributes
CUEST_GRIDKINTPLAN_PARAMETERS_THRESHOLD_COLLOCATIONdoubleAO collocation threshold.
Default:
1.0e-18CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of full-range (1/r) exchange.
Default:
1.0CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range (erf(wr)/r) exchange.
Default:
0.0CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega range-separation parameter (in inverse bohr). Must be >= 0.0.
Default:
0.0CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestGridKIntPlanParametersFittingAlgorithm_tAlgorithm used to fit the collocation of the grid-based exchange.
Default:
CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_NONECUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFFdoubleAbsolute overlap eigenvalue cutoff for the canonical orthogonalization underlying the fit. Must be > 0.0.
Default:
1.0e-6CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_CUTOFFdoubleAbsolute cutoff on the eigenvalues of the orthonormalized quadrature overlap (dimensionless recovered-norm fractions, unity for an exact grid); directions below the cutoff (including any with negative quadrature weight content) are excluded from the fit. Must be in (0.0, 1.0).
Default:
1.0e-2
variableBufferSize – [in] 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.
persistentWorkspaceDescriptor – [out] Output descriptor for persistent buffers. Must not be NULL.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.
outPlan – Unused; accepted for symmetry with
cuestGridKIntPlanCreate. 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_ARGUMENTif any of thecuestGridKIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifintPlanwas constructed with functions that exceed L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
-
cuestStatus_t cuestGridKIntPlanDestroy(cuestGridKIntPlan_t plan)#
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
cuestGridKIntPlanCreatemay be released by the user once the plan has been destroyed.- Since
v0.3.0
- Parameters:
plan – [in] Grid-K plan handle to destroy. Must not be NULL.
- Returns:
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_NULL_POINTERifplanis NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.