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,
) → cuest.bindings.cuest.CuestStatus#

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]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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

outSMatrixPointer

Optional buffer for computed overlap matrix

Returns#

status[out]CuestStatus
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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in cuda_utils.py.

densityMatrixPointer

Optional density matrix

outGradientPointer

Optional output gradient

Returns#

status[out]CuestStatus
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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 densityMatrix and outHessianBlock pointers 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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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, and numRightOrbitals are required because they size the result. The leftCoefficientMatrices, rightCoefficientMatrices, and outTensors pointers 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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBufferSizeInBytes, deviceBufferSizeInBytes; both size_t), as implemented by WorkspaceDescriptor in 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.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,
) → cuest.bindings.cuest.CuestStatus#

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 by cuestParametersCreate() with CuestParametersType.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_t structure (hostBuffer, hostBufferSizeInBytes, deviceBuffer, deviceBufferSizeInBytes), as implemented by Workspace in 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