Density Fitting Integral Plan#

group DensityFittingIntegralPlan

Functions

cuestStatus_t cuestDFIntPlanCreate(
cuestHandle_t handle,
const cuestAOBasis_t primaryBasis,
const cuestAOBasis_t auxiliaryBasis,
const cuestAOPairList_t pairList,
const cuestDFIntPlanParameters_t parameters,
cuestWorkspace_t *persistentWorkspace,
cuestWorkspace_t *temporaryWorkspace,
cuestDFIntPlan_t *outPlan
)#

Build a density-fitted integral plan (DF) for atomic orbitals.

Constructs all needed metric arrays and three-center integrals. All handles and buffers must be valid. Workspace buffers must be preallocated using sizes from workspace query.

The cuestDFIntPlan_t may be configured to treat range-separated Coulomb operators.

\[ \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_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION: Controls the fraction of full-range exchange included.

  • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION: Controls the fraction of long-range exchange included.

  • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA: Specifies the range separation parameter.

It is required that the operator specification must be positive and respect the following conditions:

  • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION \(\ge 0\).

  • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION + CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION \(\ge 0\).

  • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA \(\ge 0\).

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

The operator specification is respected by all subsequent calls involving the cuestDFIntPlan_t. The one exception is cuestDFCoulombCompute, which is always evaluated using the full-range Coulomb operator.

Example configurations:

  • PBE0 (full-range, only):

    • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION \(= 0.25\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION \(= 0\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA unused.

  • \(\omega\)B97 (long-range, only):

    • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION \(= 0.0\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION \(= 1.0\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA \(= 0.4\).

  • \(\omega\)B97M-V (full- and long-range):

    • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION \(= 0.15\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION \(= 0.85\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA \(= 0.3\).

  • HSE06 (short-range, only):

    • CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION \(= 0.25\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION \(= -0.25\).

    • CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA \(= 0.11\).

It is possible to put or create the cuestDFIntPlan_t in a state where it is no longer possible to use the cuestDFIntPlan_t for certain calculations.

  • Creating the cuestDFIntPlan_t with the CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT parameter set to a non-zero value allows the plan to be used in calls to cuestDFMOIntegralsCompute. At present, no other functions support this configuration.

  • Calls to cuestDFSymmetricDerivativeCompute using the CUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_OVERWRITE memory policy place the cuestDFIntPlan_t in a dirty state. No further compute calls involving this plan will succeed.

CUEST_STATUS_INVALID_PLAN will be returned if a compute call is made with a cuestDFIntPlan_t in an unusable state.

Note

  • The number of atoms in the primary basis handle must match the number of atoms in the auxiliary basis handle.

  • The cuestAOBasis_t primary basis handle provided here must correspond to the basis handle provided when the cuestAOPairList_t pair list handle was created.

  • It is the user’s responsibility not to destroy the cuestAOBasis_t primary basis handle, auxiliary basis handle or cuestAOPairList_t pair list handle until operations involving the cuestDFIntPlan_t plan handle are complete.

  • After the cuestAOBasis_t basis handle, auxiliary basis handle or cuestAOPairList_t pair list handle are destroyed, the cuestDFIntPlan_t plan handle is no longer valid.

  • Screening of negligible integrals computed while using this cuestDFIntPlan_t plan handle is controlled by thresholdPQ set during construction of the cuestAOPairList_t pair list handle.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • primaryBasis – [in] AO basis set for primary orbitals. Must not be NULL.

  • auxiliaryBasis – [in] AO basis set for auxiliary/fitting orbitals. The auxiliary basis set must use a pure (spherical) angular momentum representation. Must not be NULL.

  • pairList – [in] AO pair list describing sparsity. Must not be NULL.

  • parameters – [in] Density-fitting parameters structure. Must not be NULL.

  • persistentWorkspace – [in] Workspace for persistent buffers. Must not be NULL.

  • temporaryWorkspace – [in] Workspace for temporary buffers. Must not be NULL.

  • outPlan – [out] Output pointer for DF 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 cuestDFIntPlanParameters_t are invalid;

  • CUEST_STATUS_EXCEPTION if auxiliaryBasis is not pure;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFIntPlanCreateWorkspaceQuery(
cuestHandle_t handle,
const cuestAOBasis_t primaryBasis,
const cuestAOBasis_t auxiliaryBasis,
const cuestAOPairList_t pairList,
const cuestDFIntPlanParameters_t parameters,
cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
cuestDFIntPlan_t *outPlan
)#

Query workspace sizes for creating a density-fitted integral plan.

Simulates all allocations for DF plan, returning size requirements. All handles and pointers must be valid (not NULL). Output descriptors are filled on success.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • primaryBasis – [in] AO basis set for primary orbitals. Must not be NULL.

  • auxiliaryBasis – [in] AO basis set for auxiliary/fitting orbitals. The auxiliary basis set must use a pure (spherical) angular momentum representation. Must not be NULL.

  • pairList – [in] AO pair list handle. Must not be NULL.

  • parameters – [in] Density-fitting parameters structure. Must not be NULL.

  • persistentWorkspaceDescriptor – [out] Output descriptor for persistent buffers. Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers. Must not be NULL.

  • outPlan – Output pointer for DF plan handle. 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 cuestDFIntPlanParameters_t are invalid;

  • CUEST_STATUS_EXCEPTION if auxiliaryBasis is not pure;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDFIntPlanDestroy(cuestDFIntPlan_t plan)#

Destroy/free a density-fitted integral plan and all resources.

The plan handle and its memory must not be used after destruction.

Parameters:

plan – [in] DF 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.