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 query the outPCMResults handle with cuestResultsQuery using the CUEST_PCMRESULT_CONVERGED attribute to determine whether the PCM charges converged; CUEST_PCMRESULT_CONVERGED_RESIDUAL and CUEST_PCMRESULT_NUM_ITERATIONS_TAKEN report the final residual and the number of iterations performed.

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.

    Create with cuestParametersCreate() using CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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.

    Create with cuestParametersCreate() using CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMPOTENTIALCOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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 query the outPCMResults handle with cuestResultsQuery using the CUEST_PCMRESULT_CONVERGED attribute to determine whether the PCM charges returned by outQ are converged; CUEST_PCMRESULT_CONVERGED_RESIDUAL and CUEST_PCMRESULT_NUM_ITERATIONS_TAKEN report the final residual and the number of iterations performed.

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 CUEST_PCMRESULT_CONVERGED_RESIDUAL, 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 CUEST_PCMRESULT_CONVERGED and CUEST_PCMRESULT_CONVERGED_RESIDUAL 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.

    Create with cuestParametersCreate() using CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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.

    Create with cuestParametersCreate() using CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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 query the outPCMResults handle with cuestResultsQuery using the CUEST_PCMRESULT_CONVERGED attribute to determine whether the PCM charges returned by outQ are converged; CUEST_PCMRESULT_CONVERGED_RESIDUAL and CUEST_PCMRESULT_NUM_ITERATIONS_TAKEN report the final residual and the number of iterations performed.

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 CUEST_PCMRESULT_CONVERGED_RESIDUAL, 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 CUEST_PCMRESULT_CONVERGED and CUEST_PCMRESULT_CONVERGED_RESIDUAL in outPCMResults and decide whether the result is acceptable.

Since

v0.2.0

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.

    Create with cuestParametersCreate() using CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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.

Since

v0.2.0

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.

    Create with cuestParametersCreate() using CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS. Set attributes with cuestParametersConfigure().

    4 configurable attributes
    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_CONVERGENCE_THRESHOLDdouble

    Convergence threshold (max absolute residual value) for PCM charges computation.

    Default: 1e-10

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_MAX_ITERATIONSuint64_t

    Maximum number of preconditioned conjugate gradient iterations for PCM charges computation.

    Default: 200

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_FFLOAT_USAGE_MODEcuestFfloatUsageMode_t

    Parameter to control the use of ffloat compute.

    Default: CUEST_FFLOAT_USAGE_MODE_DEFAULT

    CUEST_PCMRADIIDERIVATIVECOMPUTE_PARAMETERS_JIT_USAGE_MODEcuestJITUsageMode_t

    Parameter to control the use of JIT-compiled kernels.

    Default: CUEST_JIT_USAGE_MODE_ON on CUDA 13.x+, CUEST_JIT_USAGE_MODE_OFF otherwise

  • 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.

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.

Since

v0.2.0

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

    Create with cuestParametersCreate() using CUEST_PCMINTEGRATIONGRIDCOMPUTE_PARAMETERS. There are no configurable attributes.

  • 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.

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

Since

v0.2.0

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

    Create with cuestParametersCreate() using CUEST_PCMINTEGRATIONGRIDCOMPUTE_PARAMETERS. There are no configurable attributes.

  • 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.

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.

Since

v0.2.0

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

    Create with cuestParametersCreate() using CUEST_PCMINTEGRATIONWEIGHTCOMPUTE_PARAMETERS. There are no configurable attributes.

  • 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.

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

Since

v0.2.0

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

    Create with cuestParametersCreate() using CUEST_PCMINTEGRATIONWEIGHTCOMPUTE_PARAMETERS. There are no configurable attributes.

  • 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.