Density Fitting Integral Plan#
- cuest.bindings.cuestDFIntPlanCreateWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- primaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- auxiliaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- pairList: cuest.bindings.cuest.cuestAOPairListHandle,
- parameters: cuest.bindings.cuest.Parameters,
- persistentWorkspaceDescriptor: int,
- temporaryWorkspaceDescriptor: int,
- outPlan: cuest.bindings.cuest.cuestDFIntPlanHandle,
Query workspace sizes for creating a density-fitted integral plan.
Simulates all allocations for DF plan, returning size requirements. Output descriptors are filled on success.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- primaryBasis[in]cuestAOBasisHandle
AO basis set for primary orbitals. Constructed with
cuestAOBasisCreate(). Must not be NULL.- auxiliaryBasis[in]cuestAOBasisHandle
AO basis set for auxiliary/fitting orbitals. The auxiliary basis set must use a pure (spherical) angular momentum representation. Constructed with
cuestAOBasisCreate(). Must not be NULL.- pairList[in]cuestAOPairListHandle
AO pair list handle. Constructed with
cuestAOPairListCreate(). Must not be NULL.- parameters[in]Parameters
Density-fitting parameters handle (
cuestDFIntPlanParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFINTPLAN_PARAMETERS. Must not be NULL.- persistentWorkspaceDescriptor[out]int
Output descriptor for persistent buffers. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary buffers. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outPlan[out]cuestDFIntPlanHandle
Output pointer for DF plan handle. May be NULL.
Returns#
- status[out]CuestStatus
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.
- cuest.bindings.cuestDFIntPlanCreate(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- primaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- auxiliaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- pairList: cuest.bindings.cuest.cuestAOPairListHandle,
- parameters: cuest.bindings.cuest.Parameters,
- persistentWorkspace: int,
- temporaryWorkspace: int,
- outPlan: cuest.bindings.cuest.cuestDFIntPlanHandle,
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_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):
\(\omega\)B97 (long-range, only):
CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION\(= 0.0\).
\(\omega\)B97M-V (full- and long-range):
CUEST_DFINTPLAN_PARAMETERS_EXCHANGE_FRACTION\(= 0.15\).CUEST_DFINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION\(= 0.85\).
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(), orcuestDFSymmetricDerivativeCompute()with 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 whatcuestDFMOIntegralsDerivativeCompute()requires, 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
cuestDFSymmetricDerivativeCompute()using 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.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.
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].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- primaryBasis[in]cuestAOBasisHandle
AO basis set for primary orbitals. Constructed with
cuestAOBasisCreate(). Must not be NULL.- auxiliaryBasis[in]cuestAOBasisHandle
AO basis set for auxiliary/fitting orbitals. The auxiliary basis set must use a pure (spherical) angular momentum representation. Constructed with
cuestAOBasisCreate(). Must not be NULL.- pairList[in]cuestAOPairListHandle
AO pair list handle. Constructed with
cuestAOPairListCreate(). Must not be NULL.- parameters[in]Parameters
Density-fitting parameters handle (
cuestDFIntPlanParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DFINTPLAN_PARAMETERS. Must not be NULL.- persistentWorkspace[in]int
Workspace for persistent buffers. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- temporaryWorkspace[in]int
Workspace for temporary buffers. Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- outPlan[out]cuestDFIntPlanHandle
Output pointer for DF plan handle. Must not be NULL.
Returns#
- status[out]CuestStatus
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.
- cuest.bindings.cuestDFIntPlanDestroy(
- *,
- handle: cuest.bindings.cuest.cuestDFIntPlanHandle,
Destroy/free a density-fitted integral plan and all resources.
The plan handle and its memory must not be used after destruction.
Parameters#
- handle[in]cuestDFIntPlanHandle
DF plan handle to destroy. Must not be NULL.
Returns#
- status[out]CuestStatus
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_NULL_POINTERif the plan handle is NULL;CUEST_STATUS_INVALID_TYPEif the plan handle is not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.