Polarizable Continuum Models#

group PCM

Functions

cuestStatus_t cuestPCMPotentialCompute(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMPotentialComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMPotentialMatrix
)#

Compute the PCM potential matrix using preconditioned conjugate gradient (PCG) to solve for the PCM charges.

Guesses are obtained from the inQ matrix, with the pre-allocated outQ matrix used to return the converged charges.

Convergence properties are controlled by configuring the cuestPCMPotentialComputeParameters_t structure passed as the parameters parameter.

The required temporary workspace must be allocated using the sizes returned by cuestPCMPotentialComputeWorkspaceQuery. The number of points, npoint, can be queried from the cuestPCMIntPlan_t structure using the CUEST_PCMINTPLAN_NUM_POINT query and is the sum of the numAngularPointsPerAtom array used to create the plan.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

Note that the return status is CUEST_STATUS_SUCCESS even if the PCM charges did not converge within the maximum number of iterations provided by the parameters. The caller should check the converged member of the outPCMResults handle to determine if the PCM charges converged.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM potential compute parameters (opaque handle) constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.

  • densityMatrix – [in] Total (alpha + beta) AO basis density matrix (size: nao × nao) on the GPU. Must not be NULL.

  • inQ – [in] Input guess Q vector (size: npoint) on the GPU; user should initialize this array to zeros if no guess is available. Must not be NULL.

  • outQ – [out] Output Q matrix (size: npoint) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

  • outPCMResults – [out] PCM results (opaque handle) constructed with cuestResultsCreate. Must not be NULL. Elements contained in this handle are overwritten by the calculation results.

  • outPCMPotentialMatrix – [out] Output PCM potential matrix (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success, including the case where the PCM charges did not converge within the maximum number of iterations provided by the parameters;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMPotentialComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMPotentialComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMPotentialMatrix
)#

Query the temporary workspace required for a PCM potential computation.

This function calculates the memory required for a PCM potential computation, returning host/device workspace buffer sizes in the output descriptor. The user arrays densityMatrix, inQ, outQ, outPCMResults, and outPCMPotentialMatrix may be NULL. All parameters and object handles must be valid.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM potential compute parameters constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.

  • densityMatrix – Density matrix. May be NULL.

  • inQ – Input Q matrix. May be NULL.

  • outQ – Output Q matrix. May be NULL.

  • outPCMResults – PCM results constructed with cuestResultsCreate. May be NULL.

  • outPCMPotentialMatrix – Output PCM potential matrix. May be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMDerivativeCompute(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMDerivativeComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMGradient
)#

Compute the PCM nuclear gradient.

This routine computes the derivative of the PCM energy with respect to nuclear coordinates.

Converged surface charges are computed using a preconditioned conjugate gradient (PCG) solver. Convergence behavior is controlled by the cuestPCMDerivativeComputeParameters_t structure that is packaged inside parameters. Both maximum iterations and convergence threshold may be tuned based on the specific problem.

The required temporary workspace must be allocated using the sizes returned by cuestPCMDerivativeComputeWorkspaceQuery. The number of points, npoint, can be queried from the cuestPCMIntPlan_t structure using the CUEST_PCMINTPLAN_NUM_POINT query, and is the sum of the numAngularPointsPerAtom array used to create the plan.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

It is important to note that the return status is CUEST_STATUS_SUCCESS even if the PCM charges did not converge within the maximum number of iterations provided by parameters. The caller should check the converged member of the outPCMResults handle to determine whether the PCM charges returned by outQ are converged.

In the case where maxIterations==0 , no PCG updates of the charges are performed. The values provided in inQ are used to evaluate the PCM gradient, and are copied to outQ on return. In this mode, a residual is still evaluated and reported through outPCMResults, but the charges themselves are not modified.

Similarly, if the PCG procedure reaches the maximum number of iterations without satisfying the requested convergence threshold, the gradient is still computed using the resulting (partially converged) charges. It is the caller’s responsibility to inspect the convergence information in outPCMResults and decide whether the result is acceptable.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM derivative parameters (opaque handle) constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.

  • densityMatrix – [in] Total (alpha + beta) AO basis density matrix (size: nao × nao) on the GPU. Must not be NULL.

  • inQ – [in] Input guess charges (size: npoint) on the GPU; user should initialize this array to zeros if no guess is available. Must not be NULL.

  • outQ – [out] Converged charges (size: npoint) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

  • outPCMResults – [out] PCM results (opaque handle) constructed with cuestResultsCreate. Must not be NULL. Elements contained in this handle are overwritten by the calculation results.

  • outPCMGradient – [out] Output PCM derivative (size: natoms × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success, including the case where the PCM charges did not converge within the maximum number of iterations provided by the parameters;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type; including parameters;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMDerivativeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMDerivativeComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMGradient
)#

Query the temporary workspace required for a PCM gradient computation.

Calculate the memory required for a PCM gradient computation, including the PCG solve for charges, returning host/device workspace buffer sizes in the output descriptor. The user arrays densityMatrix, inQ, outQ, outPCMResults, and outPCMGradient may be NULL. All parameters and object handles must be valid.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM derivative parameters constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.

  • densityMatrix – Density matrix. May be NULL.

  • inQ – Input Q vector. May be NULL.

  • outQ – Output Q vector. May be NULL.

  • outPCMResults – PCM results constructed with cuestResultsCreate. May be NULL.

  • outPCMGradient – Output PCM nuclear gradient. May be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type; including parameters;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMRadiiDerivativeCompute(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMRadiiDerivativeComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMRadiiGradient
)#

Compute the PCM gradient with respect to the atomic (cavity) radii.

This routine computes the derivative of the PCM energy with respect to each atomic cavity radius (the quantity needed by radius-rescaling solvent models such as DRACO), holding the electron density fixed.

Converged surface charges are computed using a preconditioned conjugate gradient (PCG) solver. Convergence behavior is controlled by the cuestPCMRadiiDerivativeComputeParameters_t structure that is packaged inside parameters. Both maximum iterations and convergence threshold may be tuned based on the specific problem.

The required temporary workspace must be allocated using the sizes returned by cuestPCMRadiiDerivativeComputeWorkspaceQuery. The number of points, npoint, can be queried from the cuestPCMIntPlan_t structure using the CUEST_PCMINTPLAN_NUM_POINT query, and is the sum of the numAngularPointsPerAtom array used to create the plan.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

It is important to note that the return status is CUEST_STATUS_SUCCESS even if the PCM charges did not converge within the maximum number of iterations provided by parameters. The caller should check the converged member of the outPCMResults handle to determine whether the PCM charges returned by outQ are converged.

In the case where maxIterations==0 , no PCG updates of the charges are performed. The values provided in inQ are used to evaluate the PCM radii gradient, and are copied to outQ on return. In this mode, a residual is still evaluated and reported through outPCMResults, but the charges themselves are not modified.

Similarly, if the PCG procedure reaches the maximum number of iterations without satisfying the requested convergence threshold, the gradient is still computed using the resulting (partially converged) charges. It is the caller’s responsibility to inspect the convergence information in outPCMResults and decide whether the result is acceptable.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM radii derivative parameters (opaque handle) constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspace – [in] Temporary workspace buffer for this operation. Must not be NULL.

  • densityMatrix – [in] Total (alpha + beta) AO basis density matrix (size: nao × nao) on the GPU. Must not be NULL.

  • inQ – [in] Input guess charges (size: npoint) on the GPU; user should initialize this array to zeros if no guess is available. Must not be NULL.

  • outQ – [out] Converged charges (size: npoint) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

  • outPCMResults – [out] PCM results (opaque handle) constructed with cuestResultsCreate. Must not be NULL. Elements contained in this handle are overwritten by the calculation results.

  • outPCMRadiiGradient – [out] Output PCM radii derivative (size: natoms) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success, including the case where the PCM charges did not converge within the maximum number of iterations provided by the parameters;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type; including parameters;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMRadiiDerivativeComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMRadiiDerivativeComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
const double *densityMatrix,
const double *inQ,
double *outQ,
cuestPCMResults_t outPCMResults,
double *outPCMRadiiGradient
)#

Query the temporary workspace required for a PCM radii gradient computation.

Calculate the memory required for a PCM radii gradient computation, including the PCG solve for charges, returning host/device workspace buffer sizes in the output descriptor. The user arrays densityMatrix, inQ, outQ, outPCMResults, and outPCMRadiiGradient may be NULL. All parameters and object handles must be valid.

Kernel and precision selection. This routine can use JIT-compiled kernels and/or reduced-precision “ffloat” compute, selected through the compute parameters:

  • CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODE (cuestJITUsageMode_t): CUEST_JIT_USAGE_MODE_ON uses JIT-compiled kernels, CUEST_JIT_USAGE_MODE_OFF uses AOT-compiled kernels. JIT-compiled kernels are only available in the cuEST CUDA 13 package; the default is CUEST_JIT_USAGE_MODE_ON in the cuEST CUDA 13 package and CUEST_JIT_USAGE_MODE_OFF in the cuEST CUDA 12 package. Requesting CUEST_JIT_USAGE_MODE_ON with the cuEST CUDA 12 package returns CUEST_STATUS_INVALID_ARGUMENT.

  • CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODE (cuestFfloatUsageMode_t) selects the compute precision: CUEST_FFLOAT_USAGE_MODE_ON requests ffloat compute, CUEST_FFLOAT_USAGE_MODE_OFF requests fp64 compute, and CUEST_FFLOAT_USAGE_MODE_DEFAULT requests ffloat compute when it is available and expected to provide a performance advantage on the present GPU architecture.

  • JIT-compiled kernels and ffloat compute may be combined. When JIT is enabled, ffloat compute can be used throughout the operation. When JIT is disabled, ffloat compute can be used only while solving for the PCM charges; the remainder of the operation always uses fp64 compute.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] PCM radii derivative parameters constructed with cuestParametersCreate. Must not be NULL.

  • temporaryWorkspaceDescriptor – [out] Output descriptor for temporary workspace sizes. Must not be NULL.

  • densityMatrix – Density matrix. May be NULL.

  • inQ – Input Q vector. May be NULL.

  • outQ – Output Q vector. May be NULL.

  • outPCMResults – PCM results constructed with cuestResultsCreate. May be NULL.

  • outPCMRadiiGradient – Output PCM radii gradient. May be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if opaque handles are not the correct type; including parameters;

  • CUEST_STATUS_INVALID_ARGUMENT if the parameters are configured to have convergence threshold less than or equal to zero;

  • CUEST_STATUS_INVALID_ARGUMENT if a parameter value is invalid, or if JIT-compiled kernels are requested with the cuEST CUDA 12 package;

  • CUEST_STATUS_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.

group PCMAdvanced

Functions

cuestStatus_t cuestPCMIntegrationGridCompute(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMIntegrationGridComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
double *outGridPoints
)#

Compute PCM integration grid point coordinates.

This routine retrieves the Cartesian coordinates of each molecular grid point used to define the PCM cavity surface. These are the grid points used by the corresponding PCM integral plan.

Since

v0.2.0

The resulting coordinates are written to a user-provided output buffer of shape (npoint × 3), containing the x, y, z coordinates of each grid point.

Temporary device workspace must be preallocated based on the size returned by cuestPCMIntegrationGridComputeWorkspaceQuery.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] Compute parameters (cuestPCMIntegrationGridComputeParameters_t) Must not be NULL

  • temporaryWorkspace – [in] Preallocated GPU workspace buffer. Must not be NULL.

  • outGridPoints – [out] Output buffer for computed grid point coordinates (size: npoint × 3) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if the handle, plan, or parameters type is incorrect;

  • CUEST_STATUS_EXCEPTION on device or internal error;

  • CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMIntegrationGridComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
const cuestPCMIntegrationGridComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
double *outGridPoints
)#

Query temporary workspace requirements for PCM grid coordinate computation.

Determines the GPU memory workspace needed to generate the coordinates of molecular integration grid points defined by the provided PCM integral plan. This function must be called before cuestPCMIntegrationGridCompute to ensure sufficient allocation.

Since

v0.2.0

Only workspace sizes are computed; input and output pointers may be NULL.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • parameters – [in] Compute parameters (cuestPCMIntegrationGridComputeParameters_t) Must not be NULL

  • temporaryWorkspaceDescriptor – [out] Output descriptor for required workspace sizes (in bytes). Must not be NULL.

  • outGridPoints – Output array for grid point coordinates. May be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if the handle, plan, or parameters type is incorrect;

  • CUEST_STATUS_EXCEPTION on device or internal error;

  • CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMIntegrationWeightCompute(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
cuestPCMIntegrationWeightComputeParametersWeightType_t weightType,
const cuestPCMIntegrationWeightComputeParameters_t parameters,
cuestWorkspace_t *temporaryWorkspace,
double *outGridWeights
)#

Compute molecular integration weights for PCM quadrature.

This routine computes the integration weights associated with each grid point in the molecular integration grid used for PCM integration. The weights returned depend on the selected weight type, specified by weightType.

Since

v0.2.0

Supported weighting schemes include:

  • CUEST_PCMINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_SWITCHING — value of the iSWIG switching function;

  • CUEST_PCMINTEGRATIONWEIGHT_PARAMETERS_WEIGHTTYPE_ZETA — value of zeta at the grid point.

The result is written to outGridWeights (size: npoint × 1). Temporary workspace must be preallocated based on cuestPCMIntegrationWeightComputeWorkspaceQuery.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • weightType – [in] Weight type to return (switching function value or zeta).

  • parameters – [in] Compute parameters (cuestPCMIntegrationWeightComputeParameters_t) Must not be NULL

  • temporaryWorkspace – [in] Preallocated GPU workspace buffer for temporary data. Must not be NULL.

  • outGridWeights – [out] Output buffer for integration weights (size: npoint × 1) on GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if the handle, plan, or parameters type is invalid;

  • CUEST_STATUS_INVALID_ARGUMENT if weightType is unrecognized;

  • CUEST_STATUS_EXCEPTION on device or internal error;

  • CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuestStatus_t cuestPCMIntegrationWeightComputeWorkspaceQuery(
cuestHandle_t handle,
const cuestPCMIntPlan_t plan,
cuestPCMIntegrationWeightComputeParametersWeightType_t weightType,
const cuestPCMIntegrationWeightComputeParameters_t parameters,
cuestWorkspaceDescriptor_t *temporaryWorkspaceDescriptor,
double *outGridWeights
)#

Query the temporary workspace required (in bytes) for computing PCM integration weights.

Determines GPU memory workspace requirements to compute integration weights on the molecular grid as defined by the provided PCM integral plan. The required workspace depends on the grid structure and selected weight type.

Since

v0.2.0

This query should be executed before calling cuestPCMIntegrationWeightCompute to ensure that sufficient device memory is available.

Parameters:

  • handle – [in] cuEST handle. Must not be NULL.

  • plan – [in] PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate. Must not be NULL.

  • weightType – [in] Weight type to return (switching function value or zeta).

  • parameters – [in] Compute parameters (cuestPCMIntegrationWeightComputeParameters_t) Must not be NULL

  • temporaryWorkspaceDescriptor – [out] Output descriptor for required temporary workspace sizes (in bytes). Must not be NULL.

  • outGridWeights – Optional output buffer for computed weights. May be NULL.

Returns:

  • CUEST_STATUS_SUCCESS on success;

  • CUEST_STATUS_INVALID_HANDLE if the cuEST handle is NULL;

  • CUEST_STATUS_NULL_POINTER if any required pointer is NULL;

  • CUEST_STATUS_INVALID_TYPE if the handle, plan, or parameters type is incorrect;

  • CUEST_STATUS_INVALID_ARGUMENT if weightType is unsupported;

  • CUEST_STATUS_EXCEPTION on device or internal error;

  • CUEST_STATUS_UNKNOWN_ERROR otherwise.