Basis#

group Basis

Functions

cuestStatus_t cuestAOShellCreate(
cuestHandle_t handle,
int32_t isPure,
uint64_t L,
uint64_t numPrimitive,
const double *exponents,
const double *coefficients,
const cuestAOShellParameters_t parameters,
cuestAOShell_t *outShell
)#

Create an AO shell object with specified parameters.

The contraction coefficients passed to this function will be used verbatim. It is the user’s responsibility to normalize the shells as desired. For more information see:

Primitive Basis Function Normalization

Parameters:

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

  • isPure – [in] Whether the shell uses pure (spherical) functions (any nonzero value is interpreted as true).

  • L – [in] Angular momentum quantum number (s=0, p=1, d=2, etc).

  • numPrimitive – [in] Number of Gaussian primitives; must be greater than zero.

  • exponents – [in] Pointer containing primitive exponents (size: numPrimitive) on the CPU. Must not be NULL.

  • coefficients – [in] Pointer containing contraction coefficients (size: numPrimitive) on the CPU. Must not be NULL.

  • parameters – [in] Handle to cuestAOShellParameters_t. Must not be NULL.

  • outShell – [out] Pointer to output shell object; receives opaque handle on success. 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 the cuEST handle or parameters are not of the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numPrimitive is zero;

  • CUEST_STATUS_EXCEPTION for unexpected error;

  • CUEST_STATUS_UNKNOWN_ERROR for non-std exceptions.

cuestStatus_t cuestAOShellDestroy(cuestAOShell_t shell)#

Destroy/free an AO shell object created with cuestAOShellCreate.

Frees all memory associated with the AO shell. After destruction, the shell handle must not be used.

Parameters:

shell – [in] Opaque AO shell handle to destroy. Must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if shell is NULL;

  • CUEST_STATUS_INVALID_TYPE if the shell handle is not of the cuestAOShell_t type.

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.

cuestStatus_t cuestAOBasisCreate(
cuestHandle_t handle,
uint64_t numAtoms,
const uint64_t *numShellsPerAtom,
const cuestAOShell_t *shells,
const cuestAOBasisParameters_t parameters,
cuestWorkspace_t *persistentWorkspace,
cuestWorkspace_t *temporaryWorkspace,
cuestAOBasis_t *outBasis
)#

Create an atomic orbital basis set object (AO basis).

The AO basis comprises multiple AO shells, grouped by atomic center.

  • All buffer pointers must be valid (not NULL).

  • Each shell, and each array entry, must be valid.

  • The persistent and temporary workspaces must be provided and preallocated.

  • The output handle is only valid after successful creation.

Important

Basis sets with “holes” in the shell angular momentum are not supported. That is, if a basis function center has a p function (L=1), it must also have an s function (L=0). If it has a d function (L=2), it must also have s and p functions present.

Note

After creating the cuestAOBasis_t basis handle, the array of cuestAOShell_t shell handles are no longer necessary and may be destroyed and any user provided input data to those shell handles may be freed.

Parameters:

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

  • numAtoms – [in] Total number of distinct atoms/centers; must be greater than zero.

  • numShellsPerAtom – [in] Array specifying number of shells per center (size: numAtoms); each must be greater than zero. CPU array, must not be NULL.

  • shells – [in] Flat array of shell handles (cuestAOShell_t), length is sum of numShellsPerAtom. CPU array, the array must not be NULL and none of the entries may be NULL.

  • parameters – [in] Handle to cuestAOBasisParameters_t. Must not be NULL.

  • persistentWorkspace – [in] Pointer to preallocated workspace for persistent buffers. Must not be NULL.

  • temporaryWorkspace – [in] Pointer to preallocated workspace for temporary buffers. Must not be NULL.

  • outBasis – [out] Pointer for output basis 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 parameter is NULL;

  • CUEST_STATUS_INVALID_TYPE if the cuEST handle, any shell handle or parameters are not of the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numAtoms == 0 or any numShellsPerAtom[i]==0;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.

cuestStatus_t cuestAOBasisCreateWorkspaceQuery(
cuestHandle_t handle,
uint64_t numAtoms,
const uint64_t *numShellsPerAtom,
const cuestAOShell_t *shells,
const cuestAOBasisParameters_t parameters,
cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
cuestAOBasis_t *outBasis
)#

Query workspace requirements for creating an AO basis object.

This function simulates the allocation logic to determine necessary persistent and temporary buffer sizes. All buffer pointers and arrays must be valid.

Parameters:

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

  • numAtoms – [in] Total number of atoms/centers; must be greater than zero.

  • numShellsPerAtom – [in] Array specifying number of shells per center (size: numAtoms); each must be greater than zero. CPU array, must not be NULL.

  • shells – [in] Flat array of shell handles (cuestAOShell_t), length is sum of numShellsPerAtom. CPU array, the array must not be NULL and none of the entries may be NULL.

  • parameters – [in] Handle to cuestAOBasisParameters_t. 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.

  • outBasis – [out] Pointer for output basis 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 the cuEST handle, any shell handle or parameters are not of the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numAtoms == 0 or any numShellsPerAtom[i]==0;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR for other errors.

cuestStatus_t cuestAOBasisDestroy(cuestAOBasis_t basis)#

Destroy/free an AO basis set object and all associated resources.

After this function is called, the basis handle must not be used.

Parameters:

basis – [in] AO basis set handle to destroy; must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if basis is NULL;

  • CUEST_STATUS_INVALID_TYPE if the cuEST AO basis handle is not of type cuestAOBasis_t.

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.

cuestStatus_t cuestAOPairListCreate(
cuestHandle_t handle,
const cuestAOBasis_t basis,
uint64_t numAtoms,
const double *xyz,
double thresholdPQ,
const cuestAOPairListParameters_t parameters,
cuestWorkspace_t *persistentWorkspace,
cuestWorkspace_t *temporaryWorkspace,
cuestAOPairList_t *outPairList
)#

Build an AO pair list structure.

Constructs a sparse or dense pair list for efficient evaluation of integrals over AOs. All input pointers and buffers must be valid and not NULL. The number of atoms and xyz array length must match. Workspace buffers must be preallocated as returned by cuestAOPairListCreateWorkspaceQuery.

The cuestAOBasis_t basis handle used to construct the cuestAOPairList_t pair list handle is not needed for the pair list handle to be valid. However, in practice, use of the pair list will also require the cuestAOBasis_t basis handle and it should not be destroyed after creating the pair list.

Parameters:

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

  • basis – [in] AO basis set handle (object describing basis for the atoms). Must not be NULL.

  • numAtoms – [in] Number of atoms in molecule or fragment. Must be greater than zero.

  • xyz – [in] Array of atomic Cartesian coordinates (length numAtoms * 3) on the CPU. Ordering of elements is row-major: \( [x_0, y_0, z_0, ...] \) . Must not be NULL.

  • thresholdPQ – [in] Sparsity threshold for pair sieve (e.g., 1e-10).

  • parameters – [in] AO pair list parameters structure. Must not be NULL.

  • persistentWorkspace – [in] Pointer to persistent workspace (preallocated). Must not be NULL.

  • temporaryWorkspace – [in] Pointer to temporary workspace (preallocated). Must not be NULL.

  • outPairList – [out] Output pointer for AO pair list 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 is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type.

  • CUEST_STATUS_INVALID_ARGUMENT if numAtoms == 0 or thresholdPQ is negative;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.

cuestStatus_t cuestAOPairListCreateWorkspaceQuery(
cuestHandle_t handle,
const cuestAOBasis_t basis,
uint64_t numAtoms,
const double *xyz,
double thresholdPQ,
const cuestAOPairListParameters_t parameters,
cuestWorkspaceDescriptor_t *persistentWorkspaceDescriptor,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
cuestAOPairList_t *outPairList
)#

Query workspace requirements for AO pair list construction.

Simulates memory usage to determine sizes of persistent and temporary buffers. All buffer and parameter pointers must be valid.

Parameters:

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

  • basis – [in] AO basis set handle (object describing basis for the atoms); must not be NULL.

  • numAtoms – [in] Number of atoms. Must be greater than zero.

  • xyz – [in] Array of atomic Cartesian coordinates (length numAtoms * 3) on the CPU. Ordering of elements is \( [x_0, y_0, z_0, ...] \). Must not be NULL.

  • thresholdPQ – [in] Sparsity threshold for pair sieve.

  • parameters – [in] AO pair list parameters structure. Must not be NULL.

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

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

  • outPairList – [out] Output pointer for AO pair list 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 numAtoms == 0;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestAOPairListDestroy(cuestAOPairList_t pairList)#

Destroy/free an AO pair list object and its resources.

The AO pair list handle and associated resources must not be used after this call.

Parameters:

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

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if pairList is NULL;

  • CUEST_STATUS_INVALID_TYPE if the cuEST AOPairList handle is not of type cuestAOPairList_t.

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.