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,
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
outTMatrixpointer 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 bycuestParametersCreate()withCuestParametersType.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_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- outTMatrixPointer
Optional buffer for computed kinetic 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.cuestKineticCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- temporaryWorkspace: int,
- outTMatrix: cuest.bindings.cuest.Pointer,
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 bycuestParametersCreate()withCuestParametersType.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_tstructure (hostBuffer,hostBufferSizeInBytes,deviceBuffer,deviceBufferSizeInBytes), as implemented byWorkspacein 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_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.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,
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 bycuestParametersCreate()withCuestParametersType.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_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.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,
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 bycuestParametersCreate()withCuestParametersType.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_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#
- 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.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,
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
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 (
cuestKineticHessianSkeletonComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.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_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.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,
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 bycuestParametersCreate()withCuestParametersType.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_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.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,
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, 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 (
cuestKineticHessianRHSComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.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_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.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,
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 bycuestParametersCreate()withCuestParametersType.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_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.