Effective Core Potentials#

group ECP

Functions

cuestStatus_t cuestECPAtomCreate(
cuestHandle_t handle,
uint64_t numElectrons,
uint64_t numShells,
const cuestECPShell_t *shells,
const cuestECPShell_t topShell,
const cuestECPAtomParameters_t parameters,
cuestECPAtom_t *outECPAtom
)#

Create an effective core potential atom from a set of ECPShell.

An ECP Atom comprises multiple ECP shells, grouped by atomic center.

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

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

  • The output handle is only valid after successful creation.

All objects on CPU.

Parameters:

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

  • numElectrons – [in] Total number of electrons corresponding to the ECP for this atom; must be greater than zero and even.

  • numShells – [in] Specifies number of shells for this atom with \( L < L_{max} \) ; must be greater than zero. \( L_{max} \) is equal to numShells.

  • shells – [in] Flat CPU array of shell handles cuestECPShell_t (size: numShells). Must not be NULL and none of the entries may be NULL. The array must contain exactly one shell per angular momentum in ascending order, i.e. the entry at index i must have \( L == i \).

  • topShell – [in] Shell handle (cuestECPShell_t) with \( L == L_{max} == \) numShells for this atom. Must not be NULL.

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

  • outECPAtom – [out] Pointer for output atom 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 opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_ARGUMENT if numElectrons == 0 or numShells == 0;

  • CUEST_STATUS_EXCEPTION if numElectrons is odd, a shell is out of order (shells[i] with \( L != i \)), or topShell does not have \( L == \) numShells;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on other errors.

cuestStatus_t cuestECPAtomDestroy(cuestECPAtom_t atom)#

Destroy/free an ECP Atom object and all associated resources.

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

Parameters:

atom – [in] ECP Atom handle to destroy; must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_NULL_POINTER if atom is NULL;

  • CUEST_STATUS_INVALID_TYPE if the cuEST ECP Atom handle is not of type cuestECPAtom_t;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.

cuestStatus_t cuestECPShellCreate(
cuestHandle_t handle,
uint64_t L,
uint64_t numPrimitive,
const uint64_t *radialPowers,
const double *coefficients,
const double *exponents,
const cuestECPShellParameters_t parameters,
cuestECPShell_t *outECPShell
)#

Create an ECP shell object with specified parameters.

All objects on CPU.

Parameters:

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

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

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

  • radialPowers – [in] Pointer to array containing radial powers (size: numPrimitive) on the CPU. Elements must be non-negative integers, e.g. >= 0. Must not be NULL.

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

  • exponents – [in] Pointer to array containing exponents (size: numPrimitive) on the CPU. Elements must be strictly positive and finite, e.g. > 0. Must not be NULL.

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

  • outECPShell – [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, or if any exponent is not strictly positive and finite (> 0);

  • CUEST_STATUS_EXCEPTION for unexpected error;

  • CUEST_STATUS_UNKNOWN_ERROR for non-std exceptions.

cuestStatus_t cuestECPShellDestroy(cuestECPShell_t shell)#

Destroy/free an ECP shell object created with cuestECPShellCreate.

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

Parameters:

shell – [in] Opaque ECP 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 cuestECPShell_t type;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR on error.