Effective Core Potentials#
- group ECPCompute
Functions
- cuestStatus_t cuestECPCompute(
- cuestHandle_t handle,
- const cuestECPIntPlan_t plan,
- const cuestECPComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *temporaryWorkspace,
- double *outECPMatrix
Compute the effective core potential integral matrix using the provided 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
cuestECPComputeWorkspaceQuery.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] cuEST handle. Must not be NULL.
plan – [in] ECP integral computation plan (opaque handle). Must not be NULL.
parameters – [in] Handle to
cuestECPComputeParameters_t. Must not be NULL.Create with
cuestParametersCreate()usingCUEST_ECPCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the local potential assembly GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa bits for fixed point emulation in the local potential assembly GEMMs. Must be in [1, 256].
Default:
55
variableBufferSize – [in] 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.
temporaryWorkspace – [in] Temporary workspace buffers for computation (preallocated). Must not be NULL.
outECPMatrix – [out] Output buffer for computed ECP matrix elements (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
- Returns:
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_ERRORotherwise;CUEST_STATUS_EXCEPTIONoften indicates variableBufferSize is too small.
- cuestStatus_t cuestECPComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestECPIntPlan_t plan,
- const cuestECPComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- double *outECPMatrix
Query the temporary workspace required (in bytes) for effective core potential matrix calculation.
This function computes the workspace requirements for a requested ECP calculation. Fill the provided workspace descriptor with host and device buffer sizes required. The
outECPMatrixpointer may be NULL.- Parameters:
handle – [in] cuEST handle. Must not be NULL.
plan – [in] ECP integral computation plan (opaque handle). Must not be NULL.
parameters – [in] Handle to
cuestECPComputeParameters_t. Must not be NULL.Create with
cuestParametersCreate()usingCUEST_ECPCOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the local potential assembly GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_ECPCOMPUTE_PARAMETERS_DETAIL_POTENTIAL_ASSEMBLY_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa bits for fixed point emulation in the local potential assembly GEMMs. Must be in [1, 256].
Default:
55
variableBufferSize – [in] 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.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
outECPMatrix – User matrix buffer. May be NULL.
- Returns:
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_ERRORotherwise.
- cuestStatus_t cuestECPDerivativeCompute(
- cuestHandle_t handle,
- const cuestECPIntPlan_t plan,
- const cuestECPDerivativeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspace_t *temporaryWorkspace,
- const double *densityMatrix,
- double *outGradient
Compute the gradient (nuclear derivative) of the effective core potential integral matrix with respect to atomic positions, contracted with a symmetric density matrix.
Both the input density matrix and the output gradient must be preallocated. The density matrix must be a symmetric (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 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] cuEST handle. Must not be NULL.
plan – [in] ECP integral computation plan (opaque handle). Must not be NULL.
parameters – [in] Handle to
cuestECPDerivativeComputeParameters_t. Must not be NULL.Create with
cuestParametersCreate()usingCUEST_ECPDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the gradient collocation GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa bits for fixed point emulation in the gradient collocation GEMMs. Must be in [1, 256].
Default:
55
variableBufferSize – [in] 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.
temporaryWorkspace – [in] Temporary workspace buffers for computation (preallocated). Must not be NULL.
densityMatrix – [in] Pointer to input density matrix (size: nao × nao) on the GPU. Density matrix must be symmetric. Must not be NULL.
outGradient – [out] Output buffer for computed ECP gradient (size: natom × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.
- Returns:
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_ERRORotherwise;CUEST_STATUS_EXCEPTIONoften indicates variableBufferSize is too small.
- cuestStatus_t cuestECPDerivativeComputeWorkspaceQuery(
- cuestHandle_t handle,
- const cuestECPIntPlan_t plan,
- const cuestECPDerivativeComputeParameters_t parameters,
- const cuestWorkspaceDescriptor_t *variableBufferSize,
- cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
- const double *densityMatrix,
- double *outGradient
Query the temporary workspace required (in bytes) for the gradient (nuclear derivative) of the effective core potential integral matrix contracted with a symmetric density matrix.
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] cuEST handle. Must not be NULL.
plan – [in] ECP integral computation plan (opaque handle). Must not be NULL.
parameters – [in] Handle to
cuestECPDerivativeComputeParameters_t. Must not be NULL.Create with
cuestParametersCreate()usingCUEST_ECPDERIVATIVECOMPUTE_PARAMETERS. Set attributes withcuestParametersConfigure().2 configurable attributes
CUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_USAGE_MODEcuestEmulationUsageMode_tControls fixed point emulation in the gradient collocation GEMMs.
Default:
CUEST_EMULATION_USAGE_MODE_DEFAULTCUEST_ECPDERIVATIVECOMPUTE_PARAMETERS_DETAIL_GRADIENT_COLLOCATION_FIXEDPOINT_EMULATION_MANTISSA_BIT_COUNTint32_tMantissa bits for fixed point emulation in the gradient collocation GEMMs. Must be in [1, 256].
Default:
55
variableBufferSize – [in] 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.
temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.
densityMatrix – Pointer to input symmetric density matrix. May be NULL.
outGradient – User buffer. May be NULL.
- Returns:
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_ERRORotherwise.