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.

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate().

parameters[in]cuestPCMPotentialComputeParameters

PCM potential compute parameters (opaque handle) constructed with cuestParametersCreate().

temporaryWorkspace[in]Workspace

Output descriptor for temporary workspace sizes. 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 cuestPCMResultsCreate.

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

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate().

parameters[in]cuestPCMPotentialComputeParameters

PCM potential compute parameters (opaque handle) constructed with cuestParametersCreate().

temporaryWorkspaceDescriptor[in]WorkspaceDescriptor

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

densityMatrix[in]Pointer

Density matrix. May be NULL.

inQ[in]Pointer

Input guess Q vector. May be NULL.

outQ[out]Pointer

Output converged Q vector. May be NULL.

outPCMResults[out]cuestPCMResults_t

PCM results (opaque handle) constructed with cuestPCMResultsCreate.

outPCMPotentialMatrix[out]Pointer

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

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().

parameters[in]cuestPCMDerivativeComputeParameters

PCM derivative parameters (opaque handle) constructed with cuestParametersCreate().

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

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

Parameters

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestPCMIntPlanHandle

PCM integral plan (opaque handle) constructed with cuestPCMIntPlanCreate().

parameters[in]cuestPCMDerivativeComputeParameters

PCM derivative parameters (opaque handle) constructed with cuestParametersCreate().

temporaryWorkspaceDescriptor[out]WorkspaceDescriptor

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

densityMatrix[in]Pointer

Density matrix. May be NULL.

inQ[in]Pointer

Input Q vector. May be NULL.

outQ[in]Pointer

Output Q vector. May be NULL.

outPCMResults[in]cuestPCMResults_t

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

outPCMGradient[in]Pointer

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_EXCEPTION or CUEST_STATUS_UNKNOWN_ERROR otherwise.