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 NULLCreate with
cuestParametersCreate()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEif the cuEST handle is NULL;CUEST_STATUS_NULL_POINTERif any required pointer is NULL;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- 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*
numPerturbationsAx 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()usingCUEST_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*
numPerturbationsAx 3*numPerturbationsB], row-major, GPU. Overwritten. Must not be NULL.
- Returns:
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEifhandleis NULL;CUEST_STATUS_NULL_POINTERifplan,parameters,temporaryWorkspace,perturbationsA,perturbationsB,densityMatrix, oroutHessianBlockis NULL;CUEST_STATUS_INVALID_ARGUMENTifnumPerturbationsA== 0 ornumPerturbationsB== 0, orperturbationsAorperturbationsBis not strictly ascending, contains a duplicate entry, or contains an atom index >= natom;CUEST_STATUS_INVALID_TYPEifhandle,plan, orparametersis not the expected opaque type;CUEST_STATUS_EXCEPTIONif an internal exception was thrown;CUEST_STATUS_UNKNOWN_ERRORif 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
densityMatrixandoutHessianBlockpointers 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()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEifhandleis NULL;CUEST_STATUS_NULL_POINTERifplan,parameters,temporaryWorkspaceDescriptor,perturbationsA, orperturbationsBis NULL (densityMatrixandoutHessianBlockmay be NULL — they are not required for a size-only query);CUEST_STATUS_INVALID_ARGUMENTifnumPerturbationsA== 0 ornumPerturbationsB== 0, orperturbationsAorperturbationsBis not strictly ascending, contains a duplicate entry, or contains an atom index >= natom;CUEST_STATUS_INVALID_TYPEifhandle,plan, orparametersis not the expected opaque type;CUEST_STATUS_EXCEPTIONif an internal exception was thrown;CUEST_STATUS_UNKNOWN_ERRORif 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*
numPerturbationsxnumLeftOrbitals[0] xnumRightOrbitals[0]], pair1 tensor [3*numPerturbationsxnumLeftOrbitals[1] xnumRightOrbitals[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()usingCUEST_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*
numPerturbationsxnumLeftOrbitals[i] xnumRightOrbitals[i]], GPU. Overwritten. Must not be NULL.
- Returns:
CUEST_STATUS_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEifhandleis NULL;CUEST_STATUS_NULL_POINTERifplan,parameters,temporaryWorkspace,perturbations,numLeftOrbitals,numRightOrbitals,leftCoefficientMatrices,rightCoefficientMatrices, oroutTensorsis NULL;CUEST_STATUS_INVALID_ARGUMENTifnumPerturbations== 0 ornumCoefficientMatrices== 0, orperturbationsis not strictly ascending, contains a duplicate entry, or contains an atom index >= natom, or anynumLeftOrbitals[i] == 0 ornumRightOrbitals[i] == 0;CUEST_STATUS_INVALID_TYPEifhandle,plan, orparametersis not the expected opaque type;CUEST_STATUS_EXCEPTIONif an internal exception was thrown;CUEST_STATUS_UNKNOWN_ERRORif 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, andoutTensorspointers may be NULL. The perturbation list,numCoefficientMatrices,numLeftOrbitals, andnumRightOrbitalsare 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()usingCUEST_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_SUCCESSon success;CUEST_STATUS_INVALID_HANDLEifhandleis NULL;CUEST_STATUS_NULL_POINTERifplan,parameters,temporaryWorkspaceDescriptor,perturbations,numLeftOrbitals, ornumRightOrbitalsis NULL (leftCoefficientMatrices,rightCoefficientMatrices, andoutTensorsmay be NULL — they are not required for a size-only query);CUEST_STATUS_INVALID_ARGUMENTifnumPerturbations== 0 ornumCoefficientMatrices== 0, orperturbationsis not strictly ascending, contains a duplicate entry, or contains an atom index >= natom, or anynumLeftOrbitals[i] == 0 ornumRightOrbitals[i] == 0;CUEST_STATUS_INVALID_TYPEifhandle,plan, orparametersis not the expected opaque type;CUEST_STATUS_EXCEPTIONif an internal exception was thrown;CUEST_STATUS_UNKNOWN_ERRORif an unrecognized error occurred.