Kinetic#

group Kinetic

Functions

cuestStatus_t cuestKineticCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
double *outTMatrix
)#

Compute the atomic orbital kinetic energy matrix (T-matrix) using the supplied integral plan.

The output buffer must be preallocated by the user and have space for (nao × nao) doubles, where nao is the number of atomic orbitals in the basis. All required temporary workspace must be allocated before calling this function, using the size returned from cuestKineticComputeWorkspaceQuery. All pointers must be valid and not 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 (cuestKineticComputeParameters_t). Must not be NULL

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

  • temporaryWorkspace – [in] Temporary workspace buffers for computation (preallocated).

  • outTMatrix – [out] Output GPU buffer for computed kinetic 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 cuestKineticComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
double *outTMatrix
)#

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

This function determines the workspace requirements for a kinetic energy matrix evaluation (such as buffer sizes), given a particular plan. The output descriptor is filled on success. User matrix buffer 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 (cuestKineticComputeParameters_t). Must not be NULL

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

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

  • outTMatrix – Optional buffer for computed kinetic matrix (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 KineticGrad

Functions

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

Compute the gradient (nuclear derivative) of the AO kinetic energy matrix (T) with respect to atomic positions, contracted with a density matrix.

The user must provide a preallocated density matrix (size nao × nao) and a preallocated output gradient buffer (size natom × 3). All required temporary workspace must be sized and allocated using the query function below.

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

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

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

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

  • outGradient – [out] Output GPU buffer for gradient (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 cuestKineticDerivativeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticDerivativeComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
double *outGradient
)#

Query the temporary workspace required (in bytes) for a kinetic energy gradient computation.

This function determines the workspace required for a kinetic energy gradient evaluation with a given plan. The output descriptor is filled on success.

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

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

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

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

  • outGradient – Optional output 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 KineticHessian

Functions

cuestStatus_t cuestKineticHessianSkeletonCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticHessianSkeletonComputeParameters_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 kinetic energy 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 T[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.

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

    Create with cuestParametersCreate() using CUEST_KINETICHESSIANSKELETONCOMPUTE_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 cuestKineticHessianSkeletonComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticHessianSkeletonComputeParameters_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 kinetic 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 (cuestKineticHessianSkeletonComputeParameters_t). Must not be NULL.

    Create with cuestParametersCreate() using CUEST_KINETICHESSIANSKELETONCOMPUTE_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 cuestKineticHessianRHSCompute(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticHessianRHSComputeParameters_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 kinetic energy 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] * dT[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 (cuestKineticHessianRHSComputeParameters_t). Must not be NULL.

    Create with cuestParametersCreate() using CUEST_KINETICHESSIANRHSCOMPUTE_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 cuestKineticHessianRHSComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestOEIntPlan_t plan,
const cuestKineticHessianRHSComputeParameters_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 kinetic 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 (cuestKineticHessianRHSComputeParameters_t). Must not be NULL.

    Create with cuestParametersCreate() using CUEST_KINETICHESSIANRHSCOMPUTE_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.