Overlap#

group Overlap

Functions

cuestStatus_t cuestOverlapCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
double *outSMatrix
)#

Compute the atomic orbital overlap matrix (S) using the provided overlap plan.

The output buffer must be preallocated and sized for nao × nao elements, where nao is the number of atomic orbitals in the basis. Temporary workspace must be allocated using size returned by cuestOverlapComputeWorkspaceQuery.

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 (cuestOverlapComputeParameters_t). Must not be NULL

    Create with cuestParametersCreate() using CUEST_OVERLAPCOMPUTE_PARAMETERS. There are no configurable attributes.

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

  • outSMatrix – [out] Output GPU buffer for computed overlap matrix elements [size: nao × nao]. 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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestOverlapComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
double *outSMatrix
)#

Query the temporary workspace required (in bytes) for overlap matrix calculation.

This function computes the workspace requirements for a requested overlap calculation. Fill the provided workspace descriptor with host and device buffer sizes required. The outSMatrix pointer 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 (cuestOverlapComputeParameters_t). Must not be NULL

    Create with cuestParametersCreate() using CUEST_OVERLAPCOMPUTE_PARAMETERS. There are no configurable attributes.

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

  • outSMatrix – User matrix buffer (may be NULL during the workspace query).

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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

group OverlapGrad

Functions

cuestStatus_t cuestOverlapDerivativeCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapDerivativeComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
const double *densityMatrix,
double *outGradient
)#

Compute the electronic gradient (derivative) of the atomic orbital overlap matrix using the supplied integral plan and density matrix.

Both the input density matrix and the output gradient must be preallocated. The density matrix must be an (nao x nao) array and the output gradient must have space for (natom x 3) elements, where nao is the number of atomic orbitals and natom the number of atoms in the system. All required temporary workspace must be allocated by the user prior to calling this function.

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 (cuestOverlapDerivativeComputeParameters_t). Must not be NULL

    Create with cuestParametersCreate() using CUEST_OVERLAPDERIVATIVECOMPUTE_PARAMETERS. There are no configurable attributes.

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

  • densityMatrix – [in] Pointer to input density matrix [size: nao × nao]. GPU array. Must not be NULL.

  • outGradient – [out] Pointer to GPU buffer for computed gradients [size: natom × 3]. 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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestOverlapDerivativeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapDerivativeComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
double *outGradient
)#

Query the temporary workspace required (in bytes) for overlap matrix gradient calculation.

This function computes the workspace requirements of a single gradient evaluation, based on the supplied plan and dimensions. The workspace descriptor is filled with host and device memory requirements. Output buffers may be NULL for the purposes of the query.

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 (cuestOverlapDerivativeComputeParameters_t). Must not be NULL

    Create with cuestParametersCreate() using CUEST_OVERLAPDERIVATIVECOMPUTE_PARAMETERS. There are no configurable attributes.

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

  • densityMatrix – Optional density matrix pointer (may be NULL).

  • outGradient – Optional buffer for computed gradient (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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

group OverlapHessian

Functions

cuestStatus_t cuestOverlapHessianSkeletonCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapHessianSkeletonComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numPerturbationsA,
const uint64_t *perturbationsA,
uint64_t numPerturbationsB,
const uint64_t *perturbationsB,
const double *densityMatrix,
double *outHessianBlock
)#

Contract the second derivatives of the AO overlap matrix against a density-like matrix over two lists of atom perturbations.

Computes H[3a+alpha, 3b+beta] = sum_{mu,nu} M[mu,nu]

  • d^2 S[mu,nu] / dX(perturbationsA[a], alpha) dX(perturbationsB[b], beta) for every atom pair (a,b) from the two perturbation lists and every Cartesian pair (alpha, beta). A perturbation entry is an atom index; its x,y,z components are implicit and expand each output dimension by a factor of three. The output block has shape [3*numPerturbationsA x 3*numPerturbationsB], stored row-major on the GPU. The density matrix M is an [nao x nao] GPU array; for the overlap contribution to the SCF Hessian pass the energy-weighted density W and apply the overall minus sign externally.

Both perturbation lists must be sorted in ascending order with no duplicate entries.

Since

v0.3.0

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

  • plan – [in] One-electron integral plan. Must not be NULL.

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

    Create with cuestParametersCreate() using CUEST_OVERLAPHESSIANSKELETONCOMPUTE_PARAMETERS. There are no configurable attributes.

  • temporaryWorkspace – [in] Preallocated temporary workspace. Must not be NULL.

  • numPerturbationsA – [in] Number of atoms in the row (A) list. Must be > 0.

  • perturbationsA – [in] Row atom indices (host, sorted, unique), size numPerturbationsA.

  • numPerturbationsB – [in] Number of atoms in the column (B) list. Must be > 0.

  • perturbationsB – [in] Column atom indices (host, sorted, unique), size numPerturbationsB.

  • densityMatrix – [in] AO density-like matrix M [nao x nao], GPU. Must not be NULL.

  • outHessianBlock – [out] Output Hessian block [3*numPerturbationsA x 3*numPerturbationsB], row-major, GPU. Overwritten. Must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL;

  • CUEST_STATUS_NULL_POINTER if plan, parameters, temporaryWorkspace, perturbationsA, perturbationsB, densityMatrix, or outHessianBlock is NULL;

  • CUEST_STATUS_INVALID_ARGUMENT if numPerturbationsA == 0 or numPerturbationsB == 0, or perturbationsA or perturbationsB is not strictly ascending, contains a duplicate entry, or contains an atom index >= natom;

  • CUEST_STATUS_INVALID_TYPE if handle, plan, or parameters is not the expected opaque type;

  • CUEST_STATUS_EXCEPTION if an internal exception was thrown;

  • CUEST_STATUS_UNKNOWN_ERROR if an unrecognized error occurred.

cuestStatus_t cuestOverlapHessianSkeletonComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapHessianSkeletonComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numPerturbationsA,
const uint64_t *perturbationsA,
uint64_t numPerturbationsB,
const uint64_t *perturbationsB,
const double *densityMatrix,
double *outHessianBlock
)#

Query the temporary workspace required for the overlap Hessian skeleton computation.

Fills the workspace descriptor with the device buffer size required. The densityMatrix and outHessianBlock pointers may be NULL. The perturbation list lengths and contents are required because they influence internal tiling.

Since

v0.3.0

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

  • plan – [in] One-electron integral plan. Must not be NULL.

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

    Create with cuestParametersCreate() using CUEST_OVERLAPHESSIANSKELETONCOMPUTE_PARAMETERS. There are no configurable attributes.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes. Must not be NULL.

  • numPerturbationsA – [in] Number of atoms in the row (A) list. Must be > 0.

  • perturbationsA – [in] Row atom indices (host, sorted, unique), size numPerturbationsA.

  • numPerturbationsB – [in] Number of atoms in the column (B) list. Must be > 0.

  • perturbationsB – [in] Column atom indices (host, sorted, unique), size numPerturbationsB.

  • densityMatrix – [in] Optional density matrix pointer (may be NULL).

  • outHessianBlock – [in] Optional output Hessian block pointer (may be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL;

  • CUEST_STATUS_NULL_POINTER if plan, parameters, temporaryWorkspaceDescriptor, perturbationsA, or perturbationsB is NULL (densityMatrix and outHessianBlock may be NULL — they are not required for a size-only query);

  • CUEST_STATUS_INVALID_ARGUMENT if numPerturbationsA == 0 or numPerturbationsB == 0, or perturbationsA or perturbationsB is not strictly ascending, contains a duplicate entry, or contains an atom index >= natom;

  • CUEST_STATUS_INVALID_TYPE if handle, plan, or parameters is not the expected opaque type;

  • CUEST_STATUS_EXCEPTION if an internal exception was thrown;

  • CUEST_STATUS_UNKNOWN_ERROR if an unrecognized error occurred.

cuestStatus_t cuestOverlapHessianRHSCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapHessianRHSComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
uint64_t numPerturbations,
const uint64_t *perturbations,
uint64_t numCoefficientMatrices,
const uint64_t *numLeftOrbitals,
const uint64_t *numRightOrbitals,
const double *leftCoefficientMatrices,
const double *rightCoefficientMatrices,
double *outTensors
)#

Compute the first derivatives of the AO overlap matrix for a list of atom perturbations and transform them into the MO basis.

For each coefficient-matrix pair i and each atom a in the perturbation list, T_i[3a+k, p, q] = sum_{mu,nu} CL_i[p,mu] * dS[mu,nu]/dX(perturbations[a],k) * CR_i[q,nu] where k in {x,y,z}. A perturbation entry is an atom index; its three Cartesian components expand the leading tensor dimension by a factor of three.

The full output is the concatenation of per-pair tensors packed as pair0 tensor [3*numPerturbations x numLeftOrbitals[0] x numRightOrbitals[0]], pair1 tensor [3*numPerturbations x numLeftOrbitals[1] x numRightOrbitals[1]], …

Coefficient matrices use row = MO, column = AO convention. Left matrices are applied first; transform cost is lowest when numLeftOrbitals[i] <= numRightOrbitals[i].

The perturbation list must be sorted in ascending order with no duplicate entries.

Since

v0.3.0

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

  • plan – [in] One-electron integral plan. Must not be NULL.

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

    Create with cuestParametersCreate() using CUEST_OVERLAPHESSIANRHSCOMPUTE_PARAMETERS. There are no configurable attributes.

  • temporaryWorkspace – [in] Preallocated temporary workspace. Must not be NULL.

  • numPerturbations – [in] Number of atoms in the perturbation list. Must be > 0.

  • perturbations – [in] Atom indices (host, sorted, unique), size numPerturbations.

  • numCoefficientMatrices – [in] Number of coefficient-matrix pairs. Must be > 0.

  • numLeftOrbitals – [in] Left orbital count per pair (host), size numCoefficientMatrices. Each entry must be > 0.

  • numRightOrbitals – [in] Right orbital count per pair (host), size numCoefficientMatrices. Each entry must be > 0.

  • leftCoefficientMatrices – [in] Concatenated left coefficient matrices; pair i has shape [numLeftOrbitals[i] x nao], GPU. Must not be NULL.

  • rightCoefficientMatrices – [in] Concatenated right coefficient matrices; pair i has shape [numRightOrbitals[i] x nao], GPU. Must not be NULL.

  • outTensors – [out] Concatenated MO-basis derivative tensors; pair i has shape [3*numPerturbations x numLeftOrbitals[i] x numRightOrbitals[i]], GPU. Overwritten. Must not be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL;

  • CUEST_STATUS_NULL_POINTER if plan, parameters, temporaryWorkspace, perturbations, numLeftOrbitals, numRightOrbitals, leftCoefficientMatrices, rightCoefficientMatrices, or outTensors is NULL;

  • CUEST_STATUS_INVALID_ARGUMENT if numPerturbations == 0 or numCoefficientMatrices == 0, or perturbations is not strictly ascending, contains a duplicate entry, or contains an atom index >= natom, or any numLeftOrbitals[i] == 0 or numRightOrbitals[i] == 0;

  • CUEST_STATUS_INVALID_TYPE if handle, plan, or parameters is not the expected opaque type;

  • CUEST_STATUS_EXCEPTION if an internal exception was thrown;

  • CUEST_STATUS_UNKNOWN_ERROR if an unrecognized error occurred.

cuestStatus_t cuestOverlapHessianRHSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestOverlapHessianRHSComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
uint64_t numPerturbations,
const uint64_t *perturbations,
uint64_t numCoefficientMatrices,
const uint64_t *numLeftOrbitals,
const uint64_t *numRightOrbitals,
const double *leftCoefficientMatrices,
const double *rightCoefficientMatrices,
double *outTensors
)#

Query the temporary workspace required for the overlap Hessian RHS computation.

Fills the workspace descriptor with the device buffer size required. The leftCoefficientMatrices, rightCoefficientMatrices, and outTensors pointers may be NULL. The perturbation list, numCoefficientMatrices, numLeftOrbitals, and numRightOrbitals are required because they size the result.

Since

v0.3.0

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

  • plan – [in] One-electron integral plan. Must not be NULL.

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

    Create with cuestParametersCreate() using CUEST_OVERLAPHESSIANRHSCOMPUTE_PARAMETERS. There are no configurable attributes.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for workspace sizes. Must not be NULL.

  • numPerturbations – [in] Number of atoms in the perturbation list. Must be > 0.

  • perturbations – [in] Atom indices (host, sorted, unique), size numPerturbations.

  • numCoefficientMatrices – [in] Number of coefficient-matrix pairs. Must be > 0.

  • numLeftOrbitals – [in] Left orbital count per pair (host), size numCoefficientMatrices. Each entry must be > 0.

  • numRightOrbitals – [in] Right orbital count per pair (host), size numCoefficientMatrices. Each entry must be > 0.

  • leftCoefficientMatrices – [in] Optional left coefficient matrices pointer (may be NULL).

  • rightCoefficientMatrices – [in] Optional right coefficient matrices pointer (may be NULL).

  • outTensors – [in] Optional output tensors pointer (may be NULL).

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if handle is NULL;

  • CUEST_STATUS_NULL_POINTER if plan, parameters, temporaryWorkspaceDescriptor, perturbations, numLeftOrbitals, or numRightOrbitals is NULL (leftCoefficientMatrices, rightCoefficientMatrices, and outTensors may be NULL &#8212; they are not required for a size-only query);

  • CUEST_STATUS_INVALID_ARGUMENT if numPerturbations == 0 or numCoefficientMatrices == 0, or perturbations is not strictly ascending, contains a duplicate entry, or contains an atom index >= natom, or any numLeftOrbitals[i] == 0 or numRightOrbitals[i] == 0;

  • CUEST_STATUS_INVALID_TYPE if handle, plan, or parameters is not the expected opaque type;

  • CUEST_STATUS_EXCEPTION if an internal exception was thrown;

  • CUEST_STATUS_UNKNOWN_ERROR if an unrecognized error occurred.