Kinetic#

cuest.bindings.cuestKineticComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspaceDescriptor: int,
outTMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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

This function computes the workspace requirements for a kinetic energy matrix calculation. Fill the provided workspace descriptor with host and device buffer sizes required. The outTMatrix 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 (cuestKineticComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICCOMPUTE_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.

outTMatrixPointer

Optional buffer for computed kinetic matrix

Returns#

status[out]CuestStatus
cuest.bindings.cuestKineticCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspace: int,
outTMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

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]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 (cuestKineticComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICCOMPUTE_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.

outTMatrix[out]Pointer

Output buffer for computed kinetic 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.cuestKineticDerivativeComputeWorkspaceQuery(
*,
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 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]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 (cuestKineticDerivativeComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICDERIVATIVECOMPUTE_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.cuestKineticDerivativeCompute(
*,
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 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]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 (cuestKineticDerivativeComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICDERIVATIVECOMPUTE_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#

status[out]CuestStatus
cuest.bindings.cuestKineticHessianSkeletonComputeWorkspaceQuery(
*,
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 kinetic Hessian skeleton computation.

This function determines the workspace required to contract the second derivatives of the AO kinetic energy 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 (cuestKineticHessianSkeletonComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICHESSIANSKELETONCOMPUTE_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.cuestKineticHessianSkeletonCompute(
*,
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 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). 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 (cuestKineticHessianSkeletonComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICHESSIANSKELETONCOMPUTE_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.cuestKineticHessianRHSComputeWorkspaceQuery(
*,
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 kinetic Hessian RHS computation.

This function determines the workspace required to compute the first derivatives of the AO kinetic energy 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 (cuestKineticHessianRHSComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICHESSIANRHSCOMPUTE_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.cuestKineticHessianRHSCompute(
*,
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 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}. 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 (cuestKineticHessianRHSComputeParameters()) initialized by cuestParametersCreate() with CuestParametersType.CUEST_KINETICHESSIANRHSCOMPUTE_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