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.

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 cuestPCMResultsCreate. 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_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.

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 – [in] Density matrix. May be NULL.

  • inQ – [in] Input Q matrix. May be NULL.

  • outQ – [in] Output Q matrix. May be NULL.

  • outPCMResults – [in] PCM results constructed with cuestPCMResultsCreate. May be NULL.

  • outPCMPotentialMatrix – [in] 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_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.

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 cuestPCMResultsCreate. 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_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.

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 – [in] Density matrix. May be NULL.

  • inQ – [in] Input Q vector. May be NULL.

  • outQ – [in] Output Q vector. May be NULL.

  • outPCMResults – [in] PCM results constructed with cuestPCMResultsCreate. May be NULL.

  • outPCMGradient – [in] 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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.