Polarizable Continuum Models

cuest.bindings.cuestPCMPotentialCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMPotentialMatrix: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

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

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMPotentialComputeParameters

PCM potential compute parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffer for this operation. Must not be NULL.

densityMatrix[in]Pointer

Density matrix (size: nao × nao) on the GPU. Must not be NULL.

inQ[in]Pointer

Input guess Q vector (size: npoint) on the GPU; can be initialized to zeros if no guess is available. Must not be NULL.

outQ[out]Pointer

Output converged Q vector (size: npoint) on the GPU. Must not be NULL.

outPCMResults[out]cuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). Must not be NULL.

outPCMPotentialMatrix[out]Pointer

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

statusCuestStatus

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

cuest.bindings.cuestPCMPotentialComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMPotentialMatrix: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Query the temporary workspace required for a PCM potential computation.

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMPotentialComputeParameters

PCM potential compute parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

densityMatrixPointer

Density matrix. May be NULL.

inQPointer

Input guess Q vector. May be NULL.

outQPointer

Output converged Q vector. May be NULL.

outPCMResultscuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). May be NULL.

outPCMPotentialMatrixPointer

Output PCM potential matrix. May be NULL.

Returns

statuscuestStatus_t

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

cuest.bindings.cuestPCMDerivativeCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMGradient: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Compute the derivative of the PCM energy with respect to nuclear coordinates.

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.

Preconditioned conjugate gradient (PCG) is used to solve for the PCG charges. The required temporary workspace must be allocated using the sizes returned by cuestPCMDerivativeComputeWorkspaceQuery(). The number of points, npoint, can be queried from the plan structure using the CUEST_PCMINTPLAN_NUM_POINT query and is the sum of the numAngularPointsPerAtom array used to create the plan.

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 whether the PCM charges converged.

If maxIterations is set to zero, 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. 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 charges obtained.

It is the caller’s responsibility to inspect the convergence information in outPCMResults and decide whether the result is acceptable.

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMDerivativeComputeParameters

PCM derivative parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffer for this operation. Must not be NULL.

densityMatrix[in]Pointer

Total (alpha + beta) AO basis density matrix (size: nao × nao) on the GPU. Must not be NULL.

inQ[in]Pointer

Input guess Q vector (size: npoint) on the GPU; can be initialized to zeros if no guess is available. Must not be NULL.

outQ[out]Pointer

Output converged Q vector (size: npoint) on the GPU. Must not be NULL.

outPCMResults[out]cuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). Must not be NULL.

outPCMGradient[out]Pointer

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

Returns

statusCuestStatus

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

cuest.bindings.cuestPCMDerivativeComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMGradient: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Query the temporary workspace required for a PCM derivative computation.

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMDerivativeComputeParameters

PCM derivative parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

densityMatrixPointer

Density matrix. May be NULL.

inQPointer

Input Q vector. May be NULL.

outQPointer

Output Q vector. May be NULL.

outPCMResultscuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). May be NULL.

outPCMGradientPointer

Output PCM derivative. May be NULL.

Returns

statuscuestStatus_t

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

cuest.bindings.cuestPCMRadiiDerivativeCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMRadiiGradient: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Compute the derivative of the PCM energy with respect to the atomic radii.

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.

Preconditioned conjugate gradient (PCG) is used to solve for the PCG charges. The required temporary workspace must be allocated using the sizes returned by cuestPCMRadiiDerivativeComputeWorkspaceQuery(). The number of points, npoint, can be queried from the plan structure using the CUEST_PCMINTPLAN_NUM_POINT query and is the sum of the numAngularPointsPerAtom array used to create the plan.

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 whether the PCM charges converged.

If maxIterations is set to zero, 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. 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 charges obtained.

It is the caller’s responsibility to inspect the convergence information in outPCMResults and decide whether the result is acceptable.

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMRadiiDerivativeComputeParameters

PCM radii derivative parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffer for this operation. Must not be NULL.

densityMatrix[in]Pointer

Total (alpha + beta) AO basis density matrix (size: nao × nao) on the GPU. Must not be NULL.

inQ[in]Pointer

Input guess Q vector (size: npoint) on the GPU; can be initialized to zeros if no guess is available. Must not be NULL.

outQ[out]Pointer

Output converged Q vector (size: npoint) on the GPU. Must not be NULL.

outPCMResults[out]cuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). Must not be NULL.

outPCMRadiiGradient[out]Pointer

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

Returns

statusCuestStatus

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

cuest.bindings.cuestPCMRadiiDerivativeComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

densityMatrix: cuest.bindings.cuest.Pointer,

inQ: cuest.bindings.cuest.Pointer,

outQ: cuest.bindings.cuest.Pointer,

outPCMResults: cuest.bindings.cuest.Results,

outPCMRadiiGradient: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

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

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]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMRadiiDerivativeComputeParameters

PCM radii derivative parameters (opaque handle) constructed with cuestParametersCreate(). Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

densityMatrixPointer

Density matrix. May be NULL.

inQPointer

Input Q vector. May be NULL.

outQPointer

Output Q vector. May be NULL.

outPCMResultscuestPCMResults_t

PCM results (opaque handle) constructed with cuestResultsCreate(). May be NULL.

outPCMRadiiGradientPointer

Output PCM radii derivative. May be NULL.

Returns

statuscuestStatus_t

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

cuest.bindings.cuestPCMIntegrationGridCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

outGridPoints: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Compute the molecular integration grid point coordinates using the provided PCM integral plan.

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

The user must provide a preallocated output buffer of shape (npoint × 3).

All required temporary workspace must be allocated using the size returned by cuestPCMIntegrationGridComputeWorkspaceQuery().

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMIntegrationGridComputeParameters

Compute parameters. Must not be NULL.

temporaryWorkspace[in]Workspace

Preallocated temporary workspace buffer for this operation. Must not be NULL.

outGridPoints[out]Pointer

Output buffer for computed grid point coordinates (size: npoint × 3) on the GPU. Must not be NULL.

Returns

status[out]CuestStatus

• 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_EXCEPTION on device or internal error;

• CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestPCMIntegrationGridComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

outGridPoints: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Query the temporary workspace required for grid coordinate computation.

This function returns the workspace needed (host/device) for a single computation, based on the provided plan. Only sizes are computed; output and grid point coordinates may be NULL.

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

parameters[in]cuestPCMIntegrationGridComputeParameters

Compute parameters. Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

outGridPointsPointer

Output buffer for grid point coordinates. May be NULL.

Returns

status[out]CuestStatus

• 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_EXCEPTION on device or internal error;

• CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestPCMIntegrationWeightCompute(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

weightType: int,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspace: int,

outGridWeights: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Compute the molecular integration weights for PCM calculations. This routine computes the integration weights associated with each grid point in the integration grid used to define the PCM cavity. The weights depend on the selected weighting scheme, 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). All required temporary workspace must be allocated using the size returned by cuestPCMIntegrationWeightComputeWorkspaceQuery().

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

weightType[in]cuestPCMIntegrationWeightComputeParametersWeightType

Weight scheme to compute (switching function value or zeta).

parameters[in]cuestPCMIntegrationWeightComputeParameters

Compute parameters. Must not be NULL.

temporaryWorkspace[in]Workspace

Preallocated temporary workspace buffer for this operation. Must not be NULL.

outGridWeights[out]Pointer

Output buffer for integration weights (size: npoint × 1) on the GPU. Must not be NULL.

Returns

status[out]CuestStatus

• 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 weightType is unrecognized;

• CUEST_STATUS_EXCEPTION on device or internal error;

• CUEST_STATUS_UNKNOWN_ERROR otherwise.

cuest.bindings.cuestPCMIntegrationWeightComputeWorkspaceQuery(

*,

handle: cuest.bindings.cuest.cuestHandle,

plan: cuest.bindings.cuest.cuestPCMIntPlanHandle,

weightType: int,

parameters: cuest.bindings.cuest.Parameters,

temporaryWorkspaceDescriptor: int,

outGridWeights: cuest.bindings.cuest.Pointer,

) → cuest.bindings.cuest.CuestStatus

Query the temporary workspace required for integration weight computation.

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 weighting scheme.

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

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate(). Must not be NULL.

weightType[in]cuestPCMIntegrationWeightComputeParametersWeightType

Weight scheme to compute (switching function value or zeta).

parameters[in]cuestPCMIntegrationWeightComputeParameters

Compute parameters. Must not be NULL.

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

outGridWeightsPointer

Output buffer for integration weights. May be NULL.

Returns

status[out]CuestStatus

• 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 weightType is unrecognized;

• CUEST_STATUS_EXCEPTION on device or internal error;

• CUEST_STATUS_UNKNOWN_ERROR otherwise.