Effective Core Potential Compute#
- cuest.bindings.cuestECPCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestECPIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- outECPMatrix: cuest.bindings.cuest.Pointer,
Compute the ECP potential matrix using the provided plan.
Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the local potential assembly, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the local potential assembly. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestECPIntPlanHandle
ECP integral plan (opaque handle) constructed with
cuestECPIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestECPComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_ECPCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for the amount of memory used to evaluate the ECP integrals. 2 GB is a good default buffer size for device memory. If an insufficient amount of memory is provided, the cuestECPCompute call will return CUEST_STATUS_EXCEPTION. If this occurs, increase the variableBufferSize and make the WorkspaceQuery and Compute calls again. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call. Host memory is currently unused. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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.- outECPMatrix[out]Pointer
Pointer to output ECP matrix (size: nao x nao) on the GPU. Must not be NULL.
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_INVALID_ARGUMENTif a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORon error.
- cuest.bindings.cuestECPComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestECPIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- outECPMatrix: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for ECP potential matrix calculation.
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestECPIntPlanHandle
ECP integral plan (opaque handle) constructed with
cuestECPIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestECPComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_ECPCOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for the amount of memory used to evaluate the ECP integrals. 2 GB is a good default buffer size for device memory. If an insufficient amount of memory is provided, the cuestECPCompute call will return CUEST_STATUS_EXCEPTION. If this occurs, increase the variableBufferSize and make the WorkspaceQuery and Compute calls again. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call. Host memory is currently unused. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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.- outECPMatrixPointer
Pointer to output ECP matrix. May be NULL.
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_INVALID_ARGUMENTif a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORon error.
- cuest.bindings.cuestECPDerivativeCompute(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestECPIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspace: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outGradient: cuest.bindings.cuest.Pointer,
Compute the gradient (nuclear derivative) of the ECP matrix with respect to atomic positions, contracted with a symmetric density matrix, using the provided plan.
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 total number of atoms in the system. All required temporary workspace must be allocated by the user prior to calling this function using size returned by
cuestECPDerivativeComputeWorkspaceQuery().Emulation selection. This routine can use fixed-point emulation of fp64 compute, selected through the compute parameters:
CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODE(cuestEmulationUsageMode_t):CUEST_EMULATION_USAGE_MODE_OFFrequests fp64 compute in the gradient collocation, andCUEST_EMULATION_USAGE_MODE_DEFAULTrequests fixed-point emulation when it is available and expected to provide a performance advantage on the present GPU architecture.CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNT(int32_t): the number of mantissa bits used by fixed-point emulation in the gradient collocation. Must be in [1, 256].
Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestECPIntPlanHandle
ECP integral plan (opaque handle) constructed with
cuestECPIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestECPDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for the amount of memory used to evaluate the ECP integrals. 2 GB is a good default buffer size for device memory. If an insufficient amount of memory is provided, the cuestECPDerivativeCompute call will return CUEST_STATUS_EXCEPTION. If this occurs, increase the variableBufferSize and make the WorkspaceQuery and Compute calls again. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call. Host memory is currently unused. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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
Pointer to input density matrix (size: nao x nao) on the GPU. Must not be NULL.
- outGradient[out]Pointer
Pointer to output gradient (size: natom * 3) on the GPU. Must not be NULL.
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_INVALID_ARGUMENTif a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORon error.
- cuest.bindings.cuestECPDerivativeComputeWorkspaceQuery(
- *,
- handle: cuest.bindings.cuest.cuestHandle,
- plan: cuest.bindings.cuest.cuestECPIntPlanHandle,
- parameters: cuest.bindings.cuest.Parameters,
- variableBufferSize: int,
- temporaryWorkspaceDescriptor: int,
- densityMatrix: cuest.bindings.cuest.Pointer,
- outGradient: cuest.bindings.cuest.Pointer,
Query the temporary workspace required (in bytes) for the gradient (nuclear derivative) of the ECP matrix contracted with a symmetric density matrix, using the provided plan.
This function computes the workspace requirements for a requested ECP gradient calculation. Fill the provided workspace descriptor with host and device buffer sizes required. The
outGradientpointer may be NULL.Parameters#
- handle[in]cuestHandle
cuEST handle. Must not be NULL.
- plan[in]cuestECPIntPlanHandle
ECP integral plan (opaque handle) constructed with
cuestECPIntPlanCreate(). Must not be NULL.- parameters[in]Parameters
Compute parameters handle (
cuestECPDerivativeComputeParameters()) initialized bycuestParametersCreate()withCuestParametersType.CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS. Must not be NULL.- variableBufferSize[in]int
User-provided descriptor for the amount of memory used to evaluate the ECP integrals. 2 GB is a good default buffer size for device memory. If an insufficient amount of memory is provided, the cuestECPDerivativeCompute call will return CUEST_STATUS_EXCEPTION. If this occurs, increase the variableBufferSize and make the WorkspaceQuery and Compute calls again. This value MUST remain unchanged between the WorkspaceQuery call and the Compute call. Host memory is currently unused. Must not be NULL. Integer address of a
cuestWorkspaceDescriptor_tstructure (hostBufferSizeInBytes,deviceBufferSizeInBytes; bothsize_t), as implemented byWorkspaceDescriptorin cuda_utils.py.- 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
Pointer to input density matrix. May be NULL.
- outGradientPointer
Pointer to output gradient. May be NULL.
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_INVALID_ARGUMENTif a parameter value is invalid;CUEST_STATUS_EXCEPTIONorCUEST_STATUS_UNKNOWN_ERRORon error.