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_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.

  • 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 when CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION is nonzero.

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 cuestGridKIntPlan_t may optionally be configured to fit the collocation, reducing the quadrature error of the grid:

  • CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM: With CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_OVERLAP_SYMMETRIC the 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 intPlan and held for the lifetime of the plan. Diagnostics of the fit may be queried from the created plan via cuestQuery; see cuestGridKIntPlanAttributes_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 with cuestOEIntPlanCreate over 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() using CUEST_GRIDKINTPLAN_PARAMETERS. Set attributes with cuestParametersConfigure().

    7 configurable attributes
    CUEST_GRIDKINTPLAN_PARAMETERS_THRESHOLD_COLLOCATIONdouble

    AO collocation threshold.

    Default: 1.0e-18

    CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of full-range (1/r) exchange.

    Default: 1.0

    CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range (erf(wr)/r) exchange.

    Default: 0.0

    CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr). Must be >= 0.0.

    Default: 0.0

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestGridKIntPlanParametersFittingAlgorithm_t

    Algorithm used to fit the collocation of the grid-based exchange.

    Default: CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_NONE

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFFdouble

    Absolute overlap eigenvalue cutoff for the canonical orthogonalization underlying the fit. Must be > 0.0.

    Default: 1.0e-6

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_CUTOFFdouble

    Absolute 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_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_ARGUMENT if any of the cuestGridKIntPlanParameters_t are invalid;

  • CUEST_STATUS_EXCEEDS_MAX_L if intPlan was constructed with functions that exceed L=4;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

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 cuestGridKIntPlanCreate call, 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 with cuestOEIntPlanCreate and must match the plan passed to the subsequent cuestGridKIntPlanCreate call. Must not be NULL.

  • parameters – [in] Grid-K plan parameters structure. Must not be NULL.

    Create with cuestParametersCreate() using CUEST_GRIDKINTPLAN_PARAMETERS. Set attributes with cuestParametersConfigure().

    7 configurable attributes
    CUEST_GRIDKINTPLAN_PARAMETERS_THRESHOLD_COLLOCATIONdouble

    AO collocation threshold.

    Default: 1.0e-18

    CUEST_GRIDKINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of full-range (1/r) exchange.

    Default: 1.0

    CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range (erf(wr)/r) exchange.

    Default: 0.0

    CUEST_GRIDKINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr). Must be >= 0.0.

    Default: 0.0

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestGridKIntPlanParametersFittingAlgorithm_t

    Algorithm used to fit the collocation of the grid-based exchange.

    Default: CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ALGORITHM_NONE

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_ORTHOGONALIZATION_CUTOFFdouble

    Absolute overlap eigenvalue cutoff for the canonical orthogonalization underlying the fit. Must be > 0.0.

    Default: 1.0e-6

    CUEST_GRIDKINTPLAN_PARAMETERS_FITTING_CUTOFFdouble

    Absolute 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_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_ARGUMENT if any of the cuestGridKIntPlanParameters_t are invalid;

  • CUEST_STATUS_EXCEEDS_MAX_L if intPlan was constructed with functions that exceed L=4;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

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 cuestGridKIntPlanCreate may 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_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if plan is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.