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 NULLCreate with
cuestParametersCreate()usingCUEST_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_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 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
outSMatrixpointer 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_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 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_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 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 NULLCreate with
cuestParametersCreate()usingCUEST_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_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 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*
numPerturbationsAx 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()usingCUEST_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*
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 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
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 (
cuestOverlapHessianSkeletonComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_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_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 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*
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 (
cuestOverlapHessianRHSComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_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*
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 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, 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 (
cuestOverlapHessianRHSComputeParameters_t). Must not be NULL.Create with
cuestParametersCreate()usingCUEST_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_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.