Potential#

cuest.bindings.cuestPotentialComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspaceDescriptor: int,
numCharges: int,
xyz: cuest.bindings.cuest.Pointer,
q: cuest.bindings.cuest.Pointer,
outVMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle).

parameters[in]cuestPotentialComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

numCharges[in]int

Number of point charges (must be greater than zero.).

xyz[in]Pointer

Optional array of charge coordinates. May be NULL.

q[in]Pointer

Optional array of charge magnitudes. May be NULL.

outVMatrix[in]Pointer

Optional output AO potential matrix buffer. May be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestPotentialCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspace: int,
numCharges: int,
xyz: cuest.bindings.cuest.Pointer,
q: cuest.bindings.cuest.Pointer,
outVMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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 \cdot \left< p\|1/\|r - R_A\|\|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().

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle).

parameters[in]cuestPotentialComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffers (preallocated for this operation). Must not be NULL.

numCharges[in]int

Number of point charges (must be greater than zero.).

xyz[in]Pointer

Array of charge coordinates in atomic units (size: numCharges x 3) on the GPU. Must not be NULL.

q[in]Pointer

Array of charge magnitudes (size: numCharges) on the GPU. Must not be NULL.

outVMatrix[out]Pointer

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

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestPotentialDerivativeComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspaceDescriptor: int,
numCharges: int,
xyz: cuest.bindings.cuest.Pointer,
q: cuest.bindings.cuest.Pointer,
densityMatrix: cuest.bindings.cuest.Pointer,
outBasisGradient: cuest.bindings.cuest.Pointer,
outChargeGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle).

parameters[in]cuestPotentialDerivativeComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes (host and device). Must not be NULL.

numCharges[in]int

Number of point charges. Must be greater than zero.

xyz[in]Pointer

Optional Cartesian coordinates of the point charges. May be NULL.

q[in]Pointer

Optional point charges. May be NULL.

densityMatrix[in]Pointer

Optional density matrix. May be NULL.

outBasisGradient[in]Pointer

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

outChargeGradient[in]Pointer

Optional output gradient buffer with respect to the point-charge coordinates. May be NULL.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestPotentialDerivativeCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspace: int,
numCharges: int,
xyz: cuest.bindings.cuest.Pointer,
q: cuest.bindings.cuest.Pointer,
densityMatrix: cuest.bindings.cuest.Pointer,
outBasisGradient: cuest.bindings.cuest.Pointer,
outChargeGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle).

parameters[in]cuestPotentialDerivativeComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffers (preallocated for this operation). Must not be NULL.

numCharges[in]int

Number of point charges. Must be greater than zero.

xyz[in]Pointer

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

q[in]Pointer

Point charges (size: numCharges) on the GPU. Must not be NULL.

densityMatrix[in]Pointer

Input density matrix (size: nao × nao) on the GPU. Must not be NULL.

outBasisGradient[out]Pointer

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

outChargeGradient[out]Pointer

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

Returns#

status[out]cuestStatus_t