Direct Integral Plan#
- cuest.bindings.cuestDirectIntPlanCreateWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- primaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- pairList: cuest.bindings.cuest.cuestAOPairListHandle,
- parameters: cuest.bindings.cuest.Parameters,
- persistentWorkspaceDescriptor: int,
- temporaryWorkspaceDescriptor: int,
- outPlan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
Query workspace sizes for creating a direct 4-center J/K integral plan.
Simulates all allocations performed by
cuestDirectIntPlanCreate(), returning the size requirements. The output descriptors are filled on success. The temporary workspace is currently unused during plan construction, so the temporary descriptor always reports zero sizes.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.- pairList[in]cuestAOPairListHandle
AO pair list handle. Constructed with
cuestAOPairListCreate(). Must not be NULL.- parameters[in]Parameters
Direct J/K plan parameters handle (
cuestDirectIntPlanParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTINTPLAN_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 (currently always zero sizes). Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outPlancuestDirectIntPlanHandle
Output pointer for the direct J/K plan handle. Ignored by the query (no plan is created); the binding always passes a real pointer.
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 the exchange-operator attributes violate their constraints (negative exchange fraction, negative fraction sum, or negative omega with a nonzero long-range fraction);CUEST_STATUS_EXCEEDS_MAX_LifprimaryBasisincludes functions exceeding L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectIntPlanCreate(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- primaryBasis: cuest.bindings.cuest.cuestAOBasisHandle,
- pairList: cuest.bindings.cuest.cuestAOPairListHandle,
- parameters: cuest.bindings.cuest.Parameters,
- persistentWorkspace: int,
- temporaryWorkspace: int,
- outPlan: cuest.bindings.cuest.cuestDirectIntPlanHandle,
Build a direct 4-center J/K integral plan.
Constructs the density-independent, per-geometry state shared by the direct 4-center Coulomb (J) and exchange (K) builders (
cuestDirectCoulombCompute(),cuestDirectSymmetricExchangeCompute()and their derivative counterparts). Creating the plan once per geometry amortizes this build across the compute calls of an SCF procedure.Workspace buffers must be preallocated using sizes from
cuestDirectIntPlanCreateWorkspaceQuery(); the persistent workspace must remain valid until the plan is destroyed.The exchange operator is owned by the plan and is parameterized in terms of the full-range and long-range components, exactly as for the density-fitted exchange plans:
\[\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}}\]CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION: Controls the fraction of full-range exchange included.CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION: Controls the fraction of long-range exchange included.CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA: Specifies the range separation parameter.
It is required that the operator specification respect the following conditions:
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION+CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION\(\ge 0\).CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA\(\ge 0\) wheneverCUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONis nonzero.
CUEST_STATUS_INVALID_ARGUMENTwill be returned if these conditions are not respected during plan creation. The operator specification is respected by the exchange (K) computes; the Coulomb (J) build always uses the full-range 1/r operator.Note
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 orcuestAOPairList_tpair list handle until operations involving thecuestDirectIntPlan_tplan handle are complete.After the
cuestAOBasis_tbasis handle orcuestAOPairList_tpair list handle are destroyed, thecuestDirectIntPlan_tplan handle is no longer valid.
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.- pairList[in]cuestAOPairListHandle
AO pair list handle. Constructed with
cuestAOPairListCreate(). Must not be NULL.- parameters[in]Parameters
Direct J/K plan parameters handle (
cuestDirectIntPlanParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_DIRECTINTPLAN_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 (currently unused; a zero-size buffer is accepted). Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- outPlan[out]cuestDirectIntPlanHandle
Output pointer for the direct J/K 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 the exchange-operator attributes violate their constraints (negative exchange fraction, negative fraction sum, or negative omega with a nonzero long-range fraction);CUEST_STATUS_EXCEEDS_MAX_LifprimaryBasisincludes functions exceeding L=4;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestDirectIntPlanDestroy(
- *,
- handle: cuest.bindings.cuest.cuestDirectIntPlanHandle,
Destroy/free a direct 4-center J/K integral plan and all resources.
The plan handle and its memory must not be used after destruction.
Parameters#
- handle[in]cuestDirectIntPlanHandle
Direct J/K 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.