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 builds the plan without a stored (fitted) three-center integral tensor; the required three-center integrals are instead recomputed on the fly. Such a plan may be used in calls to cuestDFMOIntegralsCompute, cuestDFCoulombCompute, and — for the Coulomb-only (pure functional) case — cuestDFSymmetricDerivativeCompute. It cannot be used for calculations that require exact exchange (K), such as cuestDFSymmetricExchangeCompute, cuestDFNonsymmetricExchangeCompute, or cuestDFSymmetricDerivativeCompute with a non-zero exchange contribution; such calls return CUEST_STATUS_INVALID_PLAN.

  • Creating the cuestDFIntPlan_t with the CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING parameter set to CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_NONE stores the three-center integrals fitted in the (Coulomb) fitting metric only, without the operator weighting that makes them reproduce the operator the plan describes. This is what cuestDFMOIntegralsDerivativeCompute requires, and it lets a single plan serve both operator weightings in cuestDFMOIntegralsCompute. When CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION is non-zero, the two cache weightings describe different tensors, and such a plan cannot be used for cuestDFSymmetricExchangeCompute, cuestDFNonsymmetricExchangeCompute, or cuestDFSymmetricDerivativeCompute; those calls return CUEST_STATUS_INVALID_PLAN. Without a long-range correction the setting has no effect. The setting is a property of the plan and never changes over its lifetime.

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

Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:

  • CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_USAGE_MODE (cuestEmulationUsageMode_t): CUEST_EMULATION_USAGE_MODE_OFF requests fp64 compute in the three-index fitting, and CUEST_EMULATION_USAGE_MODE_DEFAULT requests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.

  • CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT (int32_t): the number of mantissa bits used by fixed-point emulation in the three-index fitting. Must be in [1, 256].

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.

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

    10 configurable attributes
    CUEST_DFINTPLAN_PARAMETERS_FITTING_CUTOFFdouble

    Value below which metric eigenvalues are discarded during fitting.

    Default: 1.0e-12

    CUEST_DFINTPLAN_PARAMETERS_FITTING_RELATIVE_CONDITIONINGint32_t

    Should the fitting cutoff be determined in a relative or absolute sense? 0 is absolute. non-zero is relative.

    Default: 1

    CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of HF exchange: respected in DF exchange and DF derivative compute routines.

    Default: 1.0

    CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestDFIntPlanParametersFittingAlgorithm_t

    Algorithm to use when inverting the DF metric.

    Default: CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHM_QR

    CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range exchange: respected in DF exchange and DF derivative compute routines.

    Default: 0.0

    CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr): respected in DF exchange and DF derivative compute routines. Must be greater than or equal to 0.0.

    Default: 0.0

    CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTint32_t

    Skips the formation of 3-index integrals in the plan creation and uses integral direct algorithms in subsequent compute calls (where possible).

    Default: 0

    CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTINGcuestDFIntPlanParametersCacheOperatorWeighting_t

    Whether the cached 3-index integrals carry the operator weighting. Ignored when CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT is non-zero.

    Default: CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULL

    CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_t

    Controls fixed point emulation in the three-index fitting GEMMs.

    Default: CUEST_EMULATION_USAGE_MODE_DEFAULT

    CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_t

    Mantissa bits for fixed point emulation in the three-index fitting GEMMs. Must be in [1, 256].

    Default: 63

  • 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_EXCEEDS_MAX_L if primaryBasis includes functions exceeding L=4 or auxiliaryBasis includes functions exceeding L=8;

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

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

    10 configurable attributes
    CUEST_DFINTPLAN_PARAMETERS_FITTING_CUTOFFdouble

    Value below which metric eigenvalues are discarded during fitting.

    Default: 1.0e-12

    CUEST_DFINTPLAN_PARAMETERS_FITTING_RELATIVE_CONDITIONINGint32_t

    Should the fitting cutoff be determined in a relative or absolute sense? 0 is absolute. non-zero is relative.

    Default: 1

    CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of HF exchange: respected in DF exchange and DF derivative compute routines.

    Default: 1.0

    CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestDFIntPlanParametersFittingAlgorithm_t

    Algorithm to use when inverting the DF metric.

    Default: CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHM_QR

    CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range exchange: respected in DF exchange and DF derivative compute routines.

    Default: 0.0

    CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr): respected in DF exchange and DF derivative compute routines. Must be greater than or equal to 0.0.

    Default: 0.0

    CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTint32_t

    Skips the formation of 3-index integrals in the plan creation and uses integral direct algorithms in subsequent compute calls (where possible).

    Default: 0

    CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTINGcuestDFIntPlanParametersCacheOperatorWeighting_t

    Whether the cached 3-index integrals carry the operator weighting. Ignored when CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECT is non-zero.

    Default: CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULL

    CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_t

    Controls fixed point emulation in the three-index fitting GEMMs.

    Default: CUEST_EMULATION_USAGE_MODE_DEFAULT

    CUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_t

    Mantissa bits for fixed point emulation in the three-index fitting GEMMs. Must be in [1, 256].

    Default: 63

  • 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_EXCEEDS_MAX_L if primaryBasis includes functions exceeding L=4 or auxiliaryBasis includes functions exceeding L=8;

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