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).

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_POTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_POTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

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_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • 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 workspace 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. numCharges must be greater than zero.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_POTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_POTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

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 – Optional array of charge coordinates (may be NULL).

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

  • outVMatrix – 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_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • 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).

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_POTENTIALDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_POTENTIALDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

  • It is recommended to leave CUEST_FFLOAT_USAGE_MODE_OFF for general use of the potential derivative.

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_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • 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.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_POTENTIALDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_POTENTIALDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is expected to provide a performance advantage on the present GPU architecture.

  • ffloat compute is only compatible with JIT-compiled kernels. Requesting ffloat compute while JIT is disabled (CUEST_FFLOAT_USAGE_MODE_ON together with CUEST_JIT_USAGE_MODE_OFF) is not supported and returns CUEST_STATUS_INVALID_ARGUMENT.

  • It is recommended to leave CUEST_FFLOAT_USAGE_MODE_OFF for general use of the potential derivative.

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 – Optional Cartesian coordinates of the point charges. May be NULL.

  • q – Optional point charges. May be NULL.

  • densityMatrix – Optional density matrix. May be NULL.

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

  • outChargeGradient – 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_INVALID_ARGUMENT if a parameter value is invalid, if JIT-compiled kernels are requested with the cuEST CUDA 12 package, or if ffloat compute is requested while JIT is disabled (incompatible JIT/ffloat combination);

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.