Potential#

group Potential

Functions

cuestStatus_t cuestPotentialCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestPotentialComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numCharges,
const double *xyz,
const double *q,
double *outVMatrix
)#

Compute the atomic orbital nuclear attraction (potential energy) matrix (V) for given point charges.

This function computes the AO potential energy matrix for a set of point charges (typically nuclei) as:

\[ V_{pq} = \sum_{A} q_A * \left< p \left| \frac{1}{|r - R_A|} \right| q \right> \]
All input arrays must be preallocated and valid.

  • The xyz array has size numCharges × 3 (row major order: \( [x_0, y_0, z_0, x_1, y_1, z_1, ...] \) ).

  • The q array has length numCharges.

  • The output buffer outVMatrix must be preallocated for (nao × nao) doubles. Temporary workspace must be preallocated using the requirements from cuestPotentialComputeWorkspaceQuery.

Note:

  • The potential is evaluated with a positive unit test charge. To obtain nuclear attraction integrals, the q array could have negative entries. Alternatively, the q array could have positive entries and the result scaled by the charge of an electron (i.e. -1 in atomic units).

Parameters:

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

  • plan – [in] One-electron integral computation plan (opaque handle). Must not be NULL.

  • parameters – [in] Compute parameters (cuestPotentialComputeParameters_t). Must not be NULL

  • temporaryWorkspace – [in] Temporary workspace buffers, preallocated as required. Must not be NULL.

  • numCharges – [in] Number of point charges (must be greater than zero).

  • xyz – [in] Array of charge coordinates (size: numCharges × 3) in atomic units on GPU. Must not be NULL.

  • q – [in] Array of charge magnitudes (size: numCharges) on GPU. Must not be NULL.

  • outVMatrix – [out] Output AO potential matrix buffer (size: nao × nao) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

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 numCharges is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPotentialComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestPotentialComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numCharges,
const double *xyz,
const double *q,
double *outVMatrix
)#

Query the temporary workspace required (in bytes) for a potential energy matrix calculation.

This function calculates the workflow required for a potential energy matrix evaluation, returning host/device workspace buffer sizes in the output descriptor. The user arrays q, xyz, and outVMatrix may be NULL; only sizes are computed. All pointer parameters must be valid, and numCharges must be greater than zero.

Parameters:

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

  • plan – [in] One-electron integral computation plan (opaque handle). Must not be NULL.

  • parameters – [in] Compute parameters (cuestPotentialComputeParameters_t). Must not be NULL

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes (host and device). Must not be NULL.

  • numCharges – [in] Number of point charges (must be greater than zero.).

  • xyz – [in] Optional array of charge coordinates (may be NULL).

  • q – [in] Optional array of charge magnitudes (may be NULL).

  • outVMatrix – [in] Optional output AO potential matrix buffer (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 numCharges is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

group PotentialGrad

Functions

cuestStatus_t cuestPotentialDerivativeCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestPotentialDerivativeComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numCharges,
const double *xyz,
const double *q,
const double *densityMatrix,
double *outBasisGradient,
double *outChargeGradient
)#

Compute the potential integral derivatives with respect to atomic and charge coordinates, contracted with a density matrix.

This routine evaluates the derivative of the potential integrals and contracts the result with a density matrix in the AO basis. The resulting gradient is returned both with respect to the AO basis functions and with respect to the point-charge coordinates. All required temporary workspace must be sized and allocated using the corresponding workspace query function.

The user must provide:

  • A preallocated/populated density matrix of size (nao × nao).

  • A list of point charges and their Cartesian coordinates.

  • Preallocated output buffers for the AO basis gradients and charge gradients (to be overwritten).

Parameters:

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

  • plan – [in] One-electron integral computation plan (opaque handle). Must not be NULL.

  • parameters – [in] Compute parameters (cuestPotentialDerivativeComputeParameters_t). Must not be NULL

  • temporaryWorkspace – [in] Temporary workspace buffers (preallocated for this operation). Must not be NULL.

  • numCharges – [in] Number of point charges. Must be greater than zero.

  • xyz – [in] Cartesian coordinates of the point charges (size: numCharges × 3, in row-major order) on GPU. Must not be NULL.

  • q – [in] Point charges (size: numCharges) on GPU. Must not be NULL.

  • densityMatrix – [in] Input density matrix (size: nao × nao) on GPU. Must not be NULL.

  • outBasisGradient – [out] Output gradient with respect to AO basis centers (size: natom × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

  • outChargeGradient – [out] Output gradient with respect to the point-charge coordinates (size: numCharges × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

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 numCharges is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPotentialDerivativeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestPotentialDerivativeComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numCharges,
const double *xyz,
const double *q,
const double *densityMatrix,
double *outBasisGradient,
double *outChargeGradient
)#

Query the temporary workspace required to compute the potential integral derivatives with respect to atomic and charge coordinates, contracted with a density matrix.

This function determines the workspace required for a potential derivative evaluation with a given plan and point-charge specification. The output descriptor is filled on success and can be used to allocate host and device workspace buffers prior to calling cuestPotentialDerivativeCompute.

The density matrix and output gradient pointers are optional and may be NULL.

Parameters:

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

  • plan – [in] One-electron integral computation plan (opaque handle). Must not be NULL.

  • parameters – [in] Compute parameters (cuestPotentialDerivativeComputeParameters_t). Must not be NULL

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes (host and device). Must not be NULL.

  • numCharges – [in] Number of point charges. Must be greater than zero.

  • xyz – [in] Optional Cartesian coordinates of the point charges. May be NULL.

  • q – [in] Optional point charges. May be NULL.

  • densityMatrix – [in] Optional density matrix. May be NULL.

  • outBasisGradient – [in] Optional output gradient buffer with respect to AO basis centers. May be NULL.

  • outChargeGradient – [in] Optional output gradient buffer with respect to the point-charge coordinates. 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 numCharges is zero;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.