Direct Integral Plan#

group DirectIntegralPlan

Functions

cuestStatus_t cuestDirectIntPlanCreate(
cuestHandle_t handle,
const cuestAOBasis_t primaryBasis,
const cuestAOPairList_t pairList,
const cuestDirectIntPlanParameters_t parameters,
cuestWorkspace_t *persistentWorkspace,
cuestWorkspace_t *temporaryWorkspace,
cuestDirectIntPlan_t *outPlan
)#

Build a direct 4-center 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): the reduced Hermite basis of the primary shell pairs used by the direct-J engines. Creating the plan once per geometry amortizes this build across the compute calls of an SCF procedure.

The persistent workspace buffer must be preallocated using the size returned by cuestDirectIntPlanCreateWorkspaceQuery and must remain valid until the plan is destroyed.

Since

v0.3.0

Note

Parameters:
  • handle – [in] cuEST handle. Must not be NULL.

  • primaryBasis – [in] AO basis set for primary orbitals. Must not be NULL.

  • pairList – [in] AO pair list describing sparsity. Must not be NULL.

  • parameters – [in] Plan parameters (cuestDirectIntPlanParameters_t; configurable attributes: …_EXCHANGE_FRACTION, …_LRC_EXCHANGE_FRACTION and …_LRC_EXCHANGE_OMEGA — see cuestDirectIntPlanParametersAttributes_t; constraints: exchange fraction >= 0, fraction sum >= 0, and omega >= 0 when the long-range fraction is nonzero). Must not be NULL.

    Create with cuestParametersCreate() using CUEST_DIRECTINTPLAN_PARAMETERS. Set attributes with cuestParametersConfigure().

    3 configurable attributes
    CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of full-range (1/r) exchange.

    Default: 1.0

    CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range (erf(wr)/r) exchange.

    Default: 0.0

    CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr). Must be >= 0.0.

    Default: 0.0

  • persistentWorkspace – [in] Workspace for persistent buffers. Must not be NULL.

  • temporaryWorkspace – [in] Temporary workspace (scratch during construction; currently unused — a zero-size buffer is accepted). Must not be NULL.

  • outPlan – [out] Output pointer for the direct plan handle. Must not be NULL.

Returns:

  • 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 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_L if primaryBasis includes functions exceeding L=4;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDirectIntPlanCreateWorkspaceQuery(
cuestHandle_t handle,
const cuestAOBasis_t primaryBasis,
const cuestAOPairList_t pairList,
const cuestDirectIntPlanParameters_t parameters,
cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
cuestDirectIntPlan_t *outPlan
)#

Query workspace sizes for creating a direct 4-center integral plan.

Simulates all allocations performed by cuestDirectIntPlanCreate, returning the size requirements. All handles and pointers must be valid (not NULL). The output descriptor is filled on success.

Since

v0.3.0

Parameters:
  • handle – [in] cuEST handle. Must not be NULL.

  • primaryBasis – [in] AO basis set for primary orbitals. Must not be NULL.

  • pairList – [in] AO pair list handle. Must not be NULL.

  • parameters – [in] Plan parameters. Must not be NULL.

    Create with cuestParametersCreate() using CUEST_DIRECTINTPLAN_PARAMETERS. Set attributes with cuestParametersConfigure().

    3 configurable attributes
    CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdouble

    Fraction of full-range (1/r) exchange.

    Default: 1.0

    CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdouble

    Fraction of long-range (erf(wr)/r) exchange.

    Default: 0.0

    CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdouble

    Omega range-separation parameter (in inverse bohr). Must be >= 0.0.

    Default: 0.0

  • persistentWorkspaceDescriptor – [out] Output descriptor for persistent buffers. Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffers (currently always zero sizes). Must not be NULL.

  • outPlan – Output pointer for the direct plan handle. May be NULL.

Returns:

  • 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 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_L if primaryBasis includes functions exceeding L=4;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestDirectIntPlanDestroy(cuestDirectIntPlan_t plan)#

Destroy/free a direct 4-center integral plan and all resources.

The plan handle and its memory must not be used after destruction.

Since

v0.3.0

Parameters:

plan – [in] Direct plan handle to destroy. Must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if plan is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.