Effective Core Potential Integral Plan#

group ECPIntegralPlan

Functions

cuestStatus_t cuestECPIntPlanCreate(
cuestHandle_t handle,
const cuestAOBasis_t basis,
const double *xyzCPU,
uint64_t numECPAtoms,
const uint64_t *activeIndices,
const cuestECPAtom_t *activeAtoms,
const cuestECPIntPlanParameters_t parameters,
cuestWorkspace_t *persistentWorkspace,
cuestWorkspace_t *temporaryWorkspace,
cuestECPIntPlan_t *outPlan
)#

Build a plan for effective core potential integrals.

All object handles, workspaces, and output pointers must be valid (not NULL). Workspace buffers must be preallocated with required sizes (see workspace query).

Note

  • The number of atoms in the cuestAOBasis_t basis handle must match the length of the xyzCPU array.

  • The cuestAOBasis_t basis handle should define a basis set that is constructed to use the ECP functions being defined here. For example if the basis set includes a 1s orbital on a particular atom and that 1s orbital is modelled by the ECPs included here, the downstream results may be undesirable. No checking is done for such a situation.

  • It is the user’s responsibility to modify other terms that may relate to the presence of ECPs, such as the potential integrals. This will not be done automatically.

Parameters:

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

  • basis – [in] AO basis set handle. Must not be NULL.

  • xyzCPU – [in] Coordinates for full system (size: natom x 3) on the CPU. Must not be NULL.

  • numECPAtoms – [in] Number of atoms with ECPs. Must be less than or equal to total number of system atoms, natom.

  • activeIndices – [in] Indices of atoms with ECPs relative to full list of atoms (size: numECPAtoms) on the CPU. Must not be NULL. The activeIndices cannot contain indices greater than or equal to natom and cannot contain duplicate entries.

  • activeAtoms – [in] CPU array of ECP Atoms handles. Must not be NULL.

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

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

  • temporaryWorkspace – [in] Preallocated workspace for temporary buffers. Must not be NULL.

  • outPlan – [out] Output pointer for integral 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 pointer argument is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numECPAtoms is zero or the activeIndices are invalid.

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestECPIntPlanCreateWorkspaceQuery(
cuestHandle_t handle,
const cuestAOBasis_t basis,
const double *xyzCPU,
uint64_t numECPAtoms,
const uint64_t *activeIndices,
const cuestECPAtom_t *activeAtoms,
const cuestECPIntPlanParameters_t parameters,
cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
cuestECPIntPlan_t *outPlan
)#

Query workspace requirements for creating an effective core potential integral plan.

Determines persistent and temporary buffer sizes by simulating allocation logic. All handles and pointers must be valid (not NULL).

Parameters:

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

  • basis – [in] AO basis set handle. Must not be NULL.

  • xyzCPU – [in] Coordinates for full system (size: natom x 3) on the CPU. Must not be NULL.

  • numECPAtoms – [in] Number of atoms with ECPs. Must be less than or equal to total number of system atoms, natom.

  • activeIndices – [in] Indices of atoms with ECPs relative to full list of atoms (size: numECPAtoms) on the CPU. Must not be NULL. The activeIndices cannot contain indices greater than or equal to natom and cannot contain duplicate entries.

  • activeAtoms – [in] CPU array of ECP Atoms handles. Must not be NULL.

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

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

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary buffer sizing. Must not be NULL.

  • outPlan – [in] Pointer for integral 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 pointer argument is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numECPAtoms is zero or the activeIndices are invalid.

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestECPIntPlanDestroy(cuestECPIntPlan_t plan)#

Destroy and release an effective core potential integral plan and its resources.

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

Parameters:

plan – [in] 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.