Overlap#
- cuest.bindings.cuestOverlapComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- outSMatrix: cuest.bindings.cuest.Pointer,
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]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outSMatrixPointer
Optional buffer for computed overlap matrix
Returns#
- status[out]CuestStatus
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.
- cuest.bindings.cuestOverlapCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- outSMatrix: cuest.bindings.cuest.Pointer,
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]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffers for computation (preallocated). Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- outSMatrix[out]Pointer
Output buffer for computed overlap matrix elements (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
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.
- cuest.bindings.cuestOverlapDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outGradient: cuest.bindings.cuest.Pointer,
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]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- densityMatrixPointer
Optional density matrix
- outGradientPointer
Optional output gradient
Returns#
- status[out]CuestStatus
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.
- cuest.bindings.cuestOverlapDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outGradient: cuest.bindings.cuest.Pointer,
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 a 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]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffers (preallocated for this operation). Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- densityMatrix[in]Pointer
Input density matrix (size: nao × nao) on the GPU. Must not be NULL.
- outGradient[out]Pointer
Output gradient (size: natom × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- statusCuestStatus
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.
- cuest.bindings.cuestOverlapHessianSkeletonComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- perturbationsA: collections.abc.Sequence[int],
- perturbationsB: collections.abc.Sequence[int],
- densityMatrix: cuest.bindings.cuest.Pointer,
- outHessianBlock: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for the overlap Hessian skeleton computation.
This function determines the workspace required to contract the second derivatives of the AO overlap matrix against a density-like matrix over two lists of atom perturbations. The perturbation list lengths and contents are required because they influence internal tiling. The
densityMatrixandoutHessianBlockpointers may be NULL.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapHessianSkeletonComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPHESSIANSKELETONCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- perturbationsA[in]List[int]
Row (A) atom indices (host, sorted, unique).
- perturbationsB[in]List[int]
Column (B) atom indices (host, sorted, unique).
- densityMatrixPointer
Optional density matrix
- outHessianBlockPointer
Optional output Hessian block
Returns#
- status[out]CuestStatus
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_ARGUMENTifperturbationsAorperturbationsBis empty, contains an out-of-range atom index, or is not strictly ascending with no duplicates;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type.CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestOverlapHessianSkeletonCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- perturbationsA: collections.abc.Sequence[int],
- perturbationsB: collections.abc.Sequence[int],
- densityMatrix: cuest.bindings.cuest.Pointer,
- outHessianBlock: cuest.bindings.cuest.Pointer,
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). Both perturbation lists must be sorted in ascending order with no duplicate entries. The density matrix M must be preallocated (size: nao × nao). The output Hessian block must be preallocated (size: 3 × len(perturbationsA) by 3 × len(perturbationsB), row-major). All required temporary workspace must be sized and allocated using the query function above.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapHessianSkeletonComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPHESSIANSKELETONCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffers (preallocated for this operation). Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- perturbationsA[in]List[int]
Row (A) atom indices (host, sorted, unique).
- perturbationsB[in]List[int]
Column (B) atom indices (host, sorted, unique).
- densityMatrix[in]Pointer
Input density-like matrix M (size: nao × nao) on the GPU. Must not be NULL.
- outHessianBlock[out]Pointer
Output Hessian block (size: 3 × len(perturbationsA) by 3 × len(perturbationsB), row-major) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
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_ARGUMENTifperturbationsAorperturbationsBis empty, contains an out-of-range atom index, or is not strictly ascending with no duplicates;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type.CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestOverlapHessianRHSComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspaceDescriptor: int,
- perturbations: collections.abc.Sequence[int],
- numLeftOrbitals: collections.abc.Sequence[int],
- numRightOrbitals: collections.abc.Sequence[int],
- leftCoefficientMatrices: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
- outTensors: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for the overlap Hessian RHS computation.
This function determines the workspace required to compute the first derivatives of the AO overlap matrix for a list of atom perturbations and transform them into the MO basis. The perturbation list,
numLeftOrbitals, andnumRightOrbitalsare required because they size the result. TheleftCoefficientMatrices,rightCoefficientMatrices, andoutTensorspointers may be NULL.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapHessianRHSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPHESSIANRHSCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspaceDescriptor[out]int
Output descriptor for temporary workspace sizes. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- perturbations[in]List[int]
Atom indices (host, sorted, unique).
- numLeftOrbitals[in]List[int]
Left orbital count per coefficient-matrix pair (host). Each entry must be > 0.
- numRightOrbitals[in]List[int]
Right orbital count per coefficient-matrix pair (host). Each entry must be > 0.
- leftCoefficientMatricesPointer
Optional left coefficient matrices
- rightCoefficientMatricesPointer
Optional right coefficient matrices
- outTensorsPointer
Optional output tensors
Returns#
- status[out]CuestStatus
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_ARGUMENTifperturbations,numLeftOrbitals, ornumRightOrbitalsis empty, ifnumLeftOrbitalsandnumRightOrbitalshave different lengths, if anynumLeftOrbitals[i]ornumRightOrbitals[i]is 0, or ifperturbationscontains an out-of-range atom index or is not strictly ascending with no duplicates. ThenumLeftOrbitals/numRightOrbitalslength check is performed by this binding ahead of every other check, so a length mismatch is reported even when the handle or another argument is also invalid;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type.CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.
- cuest.bindings.cuestOverlapHessianRHSCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- perturbations: collections.abc.Sequence[int],
- numLeftOrbitals: collections.abc.Sequence[int],
- numRightOrbitals: collections.abc.Sequence[int],
- leftCoefficientMatrices: cuest.bindings.cuest.Pointer,
- rightCoefficientMatrices: cuest.bindings.cuest.Pointer,
- outTensors: cuest.bindings.cuest.Pointer,
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}. The perturbation list must be sorted in ascending order with no duplicate entries. Coefficient matrices use row = MO, column = AO convention; left matrices are applied first. The output is the concatenation of per-pair tensors, each preallocated with shape (3 × len(perturbations), numLeftOrbitals[i], numRightOrbitals[i]). All required temporary workspace must be sized and allocated using the query function above.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestOEIntPlanHandle
One-electron integral plan (opaque handle) constructed with
cuestOEIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestOverlapHessianRHSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_OVERLAPHESSIANRHSCOMPUTE_PARAMETERS. Must not be NULL.- temporaryWorkspace[in]int
Temporary workspace buffers (preallocated for this operation). Must not be NULL. Integer address of a
cuestWorkspace_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein cuda_utils.py.- perturbations[in]List[int]
Atom indices (host, sorted, unique).
- numLeftOrbitals[in]List[int]
Left orbital count per coefficient-matrix pair (host). Each entry must be > 0.
- numRightOrbitals[in]List[int]
Right orbital count per coefficient-matrix pair (host). Each entry must be > 0.
- leftCoefficientMatrices[in]Pointer
Concatenated left coefficient matrices; pair i has shape (numLeftOrbitals[i], nao), on the GPU. Must not be NULL.
- rightCoefficientMatrices[in]Pointer
Concatenated right coefficient matrices; pair i has shape (numRightOrbitals[i], nao), on the GPU. Must not be NULL.
- outTensors[out]Pointer
Concatenated MO-basis derivative tensors on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
Returns#
- status[out]CuestStatus
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_ARGUMENTifperturbations,numLeftOrbitals, ornumRightOrbitalsis empty, ifnumLeftOrbitalsandnumRightOrbitalshave different lengths, if anynumLeftOrbitals[i]ornumRightOrbitals[i]is 0, or ifperturbationscontains an out-of-range atom index or is not strictly ascending with no duplicates. ThenumLeftOrbitals/numRightOrbitalslength check is performed by this binding ahead of every other check, so a length mismatch is reported even when the handle or another argument is also invalid;CUEST_STATUS_INVALID_TYPEif opaque handles are not the correct type.CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORotherwise.