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_tmay 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_ARGUMENTwill 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 iscuestDFCoulombCompute, 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_OMEGAunused.
\(\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_tin a state where it is no longer possible to use thecuestDFIntPlan_tfor certain calculations.Creating the
cuestDFIntPlan_twith theCUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTparameter 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 tocuestDFMOIntegralsCompute,cuestDFCoulombCompute, and — for the Coulomb-only (pure functional) case —cuestDFSymmetricDerivativeCompute. It cannot be used for calculations that require exact exchange (K), such ascuestDFSymmetricExchangeCompute,cuestDFNonsymmetricExchangeCompute, orcuestDFSymmetricDerivativeComputewith a non-zero exchange contribution; such calls returnCUEST_STATUS_INVALID_PLAN.Creating the
cuestDFIntPlan_twith theCUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTINGparameter set toCUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_NONEstores 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 whatcuestDFMOIntegralsDerivativeComputerequires, and it lets a single plan serve both operator weightings incuestDFMOIntegralsCompute. WhenCUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONis non-zero, the two cache weightings describe different tensors, and such a plan cannot be used forcuestDFSymmetricExchangeCompute,cuestDFNonsymmetricExchangeCompute, orcuestDFSymmetricDerivativeCompute; those calls returnCUEST_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
cuestDFSymmetricDerivativeComputeusing theCUEST_DFSYMMETRICDERIVATIVECOMPUTE_MEMORY_POLICY_OVERWRITEmemory policy place thecuestDFIntPlan_tin a dirty state. No further compute calls involving this plan will succeed.
CUEST_STATUS_INVALID_PLANwill be returned if a compute call is made with acuestDFIntPlan_tin 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_OFFrequests fp64 compute in the three-index fitting, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests 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_tprimary basis handle provided here must correspond to the basis handle provided when thecuestAOPairList_tpair list handle was created.It is the user’s responsibility not to destroy the
cuestAOBasis_tprimary basis handle, auxiliary basis handle orcuestAOPairList_tpair list handle until operations involving thecuestDFIntPlan_tplan handle are complete.After the
cuestAOBasis_tbasis handle, auxiliary basis handle orcuestAOPairList_tpair list handle are destroyed, thecuestDFIntPlan_tplan handle is no longer valid.Screening of negligible integrals computed while using this
cuestDFIntPlan_tplan handle is controlled bythresholdPQset during construction of thecuestAOPairList_tpair 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()usingCUEST_DFINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().10 configurable attributes
CUEST_DFINTPLAN_PARAMETERS_FITTING_CUTOFFdoubleValue below which metric eigenvalues are discarded during fitting.
Default:
1.0e-12CUEST_DFINTPLAN_PARAMETERS_FITTING_RELATIVE_CONDITIONINGint32_tShould the fitting cutoff be determined in a relative or absolute sense? 0 is absolute. non-zero is relative.
Default:
1CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of HF exchange: respected in DF exchange and DF derivative compute routines.
Default:
1.0CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestDFIntPlanParametersFittingAlgorithm_tAlgorithm to use when inverting the DF metric.
CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range exchange: respected in DF exchange and DF derivative compute routines.
Default:
0.0CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega 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.0CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTint32_tSkips the formation of 3-index integrals in the plan creation and uses integral direct algorithms in subsequent compute calls (where possible).
Default:
0CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTINGcuestDFIntPlanParametersCacheOperatorWeighting_tWhether the cached 3-index integrals carry the operator weighting. Ignored when
CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTis non-zero.Default:
CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULLCUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the three-index fitting GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa 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_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 thecuestDFIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifprimaryBasisincludes functions exceeding L=4 orauxiliaryBasisincludes functions exceeding L=8;CUEST_STATUS_EXCEPTIONifauxiliaryBasisis not pure;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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()usingCUEST_DFINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().10 configurable attributes
CUEST_DFINTPLAN_PARAMETERS_FITTING_CUTOFFdoubleValue below which metric eigenvalues are discarded during fitting.
Default:
1.0e-12CUEST_DFINTPLAN_PARAMETERS_FITTING_RELATIVE_CONDITIONINGint32_tShould the fitting cutoff be determined in a relative or absolute sense? 0 is absolute. non-zero is relative.
Default:
1CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of HF exchange: respected in DF exchange and DF derivative compute routines.
Default:
1.0CUEST_DFINTPLAN_PARAMETERS_FITTING_ALGORITHMcuestDFIntPlanParametersFittingAlgorithm_tAlgorithm to use when inverting the DF metric.
CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range exchange: respected in DF exchange and DF derivative compute routines.
Default:
0.0CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega 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.0CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTint32_tSkips the formation of 3-index integrals in the plan creation and uses integral direct algorithms in subsequent compute calls (where possible).
Default:
0CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTINGcuestDFIntPlanParametersCacheOperatorWeighting_tWhether the cached 3-index integrals carry the operator weighting. Ignored when
CUEST_DFINTPLAN_PARAMETERS_THREE_INDEX_INTEGRAL_DIRECTis non-zero.Default:
CUEST_DFINTPLAN_PARAMETERS_CACHE_OPERATOR_WEIGHTING_FULLCUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the three-index fitting GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_DFINTPLAN_PARAMETERS_DETAIL_THREE_INDEX_FITTING_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa 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_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 thecuestDFIntPlanParameters_tare invalid;CUEST_STATUS_EXCEEDS_MAX_LifprimaryBasisincludes functions exceeding L=4 orauxiliaryBasisincludes functions exceeding L=8;CUEST_STATUS_EXCEPTIONifauxiliaryBasisis not pure;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
-
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_SUCCESSon success;CUEST_STATUS_NULL_POINTERifplanis NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.