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,cuestDirectSymmetricExchangeComputeand 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
cuestDirectIntPlanCreateWorkspaceQueryand must remain valid until the plan is destroyed.- Since
v0.3.0
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] 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 — seecuestDirectIntPlanParametersAttributes_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()usingCUEST_DIRECTINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().3 configurable attributes
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of full-range (1/r) exchange.
Default:
1.0CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range (erf(wr)/r) exchange.
Default:
0.0CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega 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_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.
- 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()usingCUEST_DIRECTINTPLAN_PARAMETERS. Set attributes withcuestParametersConfigure().3 configurable attributes
CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTIONdoubleFraction of full-range (1/r) exchange.
Default:
1.0CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTIONdoubleFraction of long-range (erf(wr)/r) exchange.
Default:
0.0CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGAdoubleOmega 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_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.
-
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_SUCCESSon success;CUEST_STATUS_NULL_POINTERifplanis NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.