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

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 by cuestParametersCreate() with CuestParametersType.CUEST_DIRECTINTPLAN_PARAMETERS. Must not be NULL.

persistentWorkspaceDescriptor[out]int

Output descriptor for persistent buffers. Must not be NULL. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

temporaryWorkspaceDescriptor[out]int

Output descriptor for temporary buffers (currently always zero sizes). Must not be NULL. Integer address of a cuestWorkspaceDescriptor_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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}}\]

It is required that the operator specification respect the following conditions:

CUEST_STATUS_INVALID_ARGUMENT will 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

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 by cuestParametersCreate() with CuestParametersType.CUEST_DIRECTINTPLAN_PARAMETERS. Must not be NULL.

persistentWorkspace[in]int

Workspace for persistent buffers. Must not be NULL. Integer address of a cuestWorkspace_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in cuda_utils.py.

outPlan[out]cuestDirectIntPlanHandle

Output pointer for the direct J/K plan handle. Must not be NULL.

Returns#

status[out]CuestStatus
cuest.bindings.cuestDirectIntPlanDestroy(
*,
handle: cuest.bindings.cuest.cuestDirectIntPlanHandle,
) → cuest.bindings.cuest.CuestStatus#

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