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, ) → cuest.bindings.cuest.CuestStatus#

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. 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. Must not be NULL.
pairList[in]CuestAOPairListHandle: AO pair list handle. Must not be NULL.
parameters[in]CuestDFIntPlanParametersHandle: Density-fitting parameters structure. Must not be NULL.
persistentWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for persistent buffers. Must not be NULL.
temporaryWorkspaceDescriptor[out]WorkspaceDescriptor: Output descriptor for temporary buffers. Must not be NULL.
outPlanCuestDFIntPlanHandle: Output pointer for DF plan handle. May be NULL.

Returns#

status[out]cuestStatus_t

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.

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, ) → cuest.bindings.cuest.CuestStatus#

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]CuestHandle: cuEST handle. Must not be NULL.
primaryBasis[in]CuestAOBasisHandle: AO basis set for primary orbitals. 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. Must not be NULL.
pairList[in]CuestAOPairListHandle: AO pair list handle. Must not be NULL.
parameters[in]CuestDFIntPlanParametersHandle: Density-fitting parameters structure. Must not be NULL.
persistentWorkspace[in]Workspace: Workspace for persistent buffers. Must not be NULL.
temporaryWorkspace[in]Workspace: Workspace for temporary buffers. Must not be NULL.
outPlan[out]CuestDFIntPlanHandle: Output pointer for DF plan handle. Must not be NULL.

Returns#

status[out]cuestStatus_t

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.

cuest.bindings.cuestDFIntPlanDestroy( *, handle: cuest.bindings.cuest.cuestDFIntPlanHandle, ) → cuest.bindings.cuest.CuestStatus#

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_t

CUEST_STATUS_SUCCESS on success;
CUEST_STATUS_NULL_POINTER if the plan handle is NULL;
CUEST_STATUS_INVALID_TYPE if the plan handle is not the correct type;
CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.