Interface to ddx by A. Mikhalev, A. Jha, M. Nottoli and M. F. Herbst¶

Code author: Michael F. Herbst

Section author: Michael F. Herbst

PSI4 contains code to interface to the ddx FORTRAN library developed by A. Mikhalev et. al.. The library provides a linear-scaling implementation of standard continuum solvation models using a domain-decomposition ansatz [Cances:2013:054111] [Stamm:2016:054101]. Currently the conductor-like screening model (COSMO) [Klamt:1993:799] [Lipparini:2014:184108], the polarisable continuum model (PCM) [Tomasi:2005:2999] [Nottoli:2019:6061] and the linearized poisson-boltzmann model (LPB) [Lu:2008:973] [Jha:2023:104105] are supported. No additional licence or configuration is required to use ddx with Psi4.

Installation¶

Binary

ddx is available for Linux and macOS in form of the pyddx package on conda-forge and on pypi.
To install from conda run conda install pyddx -c conda-forge.
To remove a conda installation, conda remove pyddx.

Source

If using PSI4 built from source and you want ddx installed as well, enable it as a feature with ENABLE_ddx, and let the build system fetch and install it.

Using dd-based continum solvation models¶

In PSI4 two option to enable continuum solvation models are currently implemented using either the PCMSolver or ddx package. PCMSolver is based on a boundary-element discretisation [Cances:1998:309], while ddx is based on a domain decomposition approach [Cances:2013:054111] making it linear scaling. For more details about PCMSolver see the section on PCMsolver. For a concise introduction to the theory behind ddx or further literature references see the ddx documentation.

The usage of ddx-based solvation models is enabled by specifying DDX true in your input file. The solvation model itself is selected using the DDX_MODEL parameter. Additionally the definition of the solvent and solute cavity is required and further parameters allow to influence details of discretisation, numerical integration and iterative solvers, see the next sections for details.

Note

At present dd-based solvation models can only be used for energy calculations with SCF wavefunctions. All ERI algorithms (PK, OUT_OF_CORE, DIRECT, DF, CD) are supported.

Warning

Currently the ddx interface cannot exploit molecular point group symmetry.

Warning

Analytic gradients and Hessians are currently not available with dd-based solvation models.

A minimal input for a Hartree–Fock calculation with dd-based PCM would look like the following:

import psi4
nh3 = psi4.geometry("""
    N     -0.0000000001    -0.1040380466      0.0000000000
    H     -0.9015844116     0.4818470201     -1.5615900098
    H     -0.9015844116     0.4818470201      1.5615900098
    H      1.8031688251     0.4818470204      0.0000000000
    symmetry c1
    no_reorient
    no_com
    units bohr
    """)

psi4.set_options({
    "basis": "sto-3g",
    "scf_type": "pk",
    "ddx": True,
    "ddx_model":     "pcm",
    "ddx_solvent":   "water",
    "ddx_radii_set": "uff",
})

scf_e = psi4.energy('SCF')

Solvent model and solvent cavity definition¶

Beyond setting DDX to true and selecting a solvent model using DDX_MODEL, the definition of the solvent is mandatory. Regularly one might want to influence the setup of the solvent cavity as well.

The solvent can be defined either by directly providing a dielectric constant using DDX_SOLVENT_EPSILON or by looking up the dielectric constant in from a solvent trivial name provided by DDX_SOLVENT (e.g. water, ethanol, cis-1,2-dimethylcyclohexane). By convention solvent names are all lowercase and use dashes (-) to separate quantifiers like o, n etc. The full list understood by ddx can be obtained using

import pyddx
print(pyddx.data.solvent_epsilon.keys())

For when an LPB solvent model is selected (DDX_MODEL is LPB) additionally the Debye-Hückel parameter DDX_SOLVENT_KAPPA needs to be provided (in units of inverse Bohr or inverse Angström, depending on the unit used to define the molecular geometry). pyddx provides a handy utility function to compute the Debye-Hückel parameter. For example

import pyddx
from qcelemental import constants

list_of_ions = [(+1, 0.1), (-1, 0.1)]
dielectric_constant = pyddx.data.solvent_epsilon["water"]
temperature = 298.15  # Kelvin
kappa_invbohr = pyddx.solvent_kappa(list_of_ions, dielectric_constant, temperature)
kappa_invang = kappa_invbohr / constants.bohr2angstroms

computes the parameter (in inverse Angström) for a 0.1 mol/l solution of sodium chloride in water, thus a solution woith 0.1 mol/l of a +1-charged ion and 0.1 mol/l of a -1-charged ion.

The cavity in ddx is defined as a union of spheres around each atom. Usually the spehere radii for each atom are determined using a standard set of tabulated radii per atomic species, determined by the DDX_RADII_SET parameter. Currently bondi [Bondi:1964:441] and uff [Rappe:1992:114] are supported for DDX_RADII_SET with uff selected by default. These radius values are conventionally scaled by an additional factor before use, conventionally 1.1 for uff and 1.2 for bondi. Customisation of the scaling is possible using the DDX_RADII_SCALING parameter. A more fine-grained control over the sphere radii is available by explicitly providing a list of radii (one per atom, exactly in the order of the input geometry) using the DDX_RADII parameter. Note that the same unit as for the molecular input is expected for the radii.

DDX ¶

DDX boolean for ddx module

Type: boolean

Default: false

DDX_MODEL ¶

Switch available solvation models

Type: string

Possible Values: PCM, COSMO, LPB

Default: PCM

DDX_RADII ¶

Custom cavity radii. One per atom, uses the unit of the molecule.

Type: array

Default: No Default

DDX_RADII_SCALING ¶

Scaling factor for cavity spheres. Ignored if RADII is set. The default depends on the radii set chosen.

Type: double

Default: 1.1

DDX_RADII_SET ¶

Radius set for cavity spheres. Ignored if RADII is set.

Type: string

Possible Values: UFF, BONDI

Default: UFF

DDX_SOLVENT_EPSILON ¶

Dielectric constant of the solvent to use

Type: double

Default: 0

DDX_SOLVENT ¶

Solvent to use. Not case sensitive. Ignored if SOLVENT_EPSILON is set.

Type: string

Default: No Default

DDX_SOLVENT_KAPPA ¶

Debye-Hückel parameter of the solvent to use. Ignored if DDX_MODEL is not LPB; mandatory for LPB. Uses the unit of the molecule (i.e. either ang^{-1} or bohr^{-1}).

Type: double

Default: 0

Numerical integration and discretisation parameters¶

These parameters can be altered to balance the cost and accuracy of the implict description of the solvation.

DDX_SOLUTE_RADIAL_POINTS and DDX_SOLUTE_SPHERICAL_POINTS influence the accuracy of the numerical grid used to obtain the representation of the electric potential / field of the solute density, since a standard DFT integration grid is used to obtain these quantities. In contrast to the integration of DFT quantities much lower accuracy is required, such that for this step considerably smaller grids are employed. If extremely high accuracy reference solutions are required, the DDX DFT integration parameters might need to be increased, but this is rarely needed.

DDX_LMAX and DDX_N_LEBEDEV determine the accuracy of the computations on the boundary of the spheres around each atom performed by DDX. DDX_LMAX determines the largest angular momentum of the spherical harmonics basis used to discretise quantities on the atomic spheres and DDX_N_LEBEDEV determines the number of points of the Lebedev angular grid used for integration on the spheres. DDX_N_LEBEDEV should be chosen higher than DDX_SOLUTE_SPHERICAL_POINTS and the defaults are usually good.

DDX_SOLUTE_RADIAL_POINTS ¶

Number of radial points used to compute the integrals for DDX calculations

Type: integer

Default: 35

DDX_SOLUTE_SPHERICAL_POINTS ¶

Number of spherical points used to compute the solute electric potential/field integrals for DDX calculations (A Lebedev Points number)

Type: integer

Default: 110

DDX_LMAX ¶

Maximal degree of modelling spherical harmonics

Type: integer

Default: 9

DDX_N_LEBEDEV ¶

Number of Lebedev grid points to use. (A Lebedev Points number)

Type: integer

Default: 302

Iterative solver parameters¶

These parameters determine how the forward and adjoint linear systems of the solvation model are solved. Usually these parameters do not need to be changed. Occasionally DDX_SOLVATION_CONVERGENCE might need to be adapted, e.g. if only a very crude or a highly accurate SCF solution is targeted.

DDX_DIIS_MAX_VECS ¶

Number of previous iterates to use in DIIS acceleration inside DDX

Type: integer

Default: 20

DDX_MAXITER ¶

Maximal number of iterations used inside DDX

Type: integer

Default: 100

DDX_SOLVATION_CONVERGENCE ¶

Tolerance to which DDX linear systems are solved

Type: conv double

Default: 1e-8

Further keywords for ddx¶

These parameter should rarely require changes. In particular DDX_ETA, DDX_SHIFT and DDX_LOGFILE are expert parameters and should not be altered beyond debugging.

DDX_ETA ¶

Regularization parameter for characteristic function of sphere overlap. Advanced parameter, which usually does not need to be modified. Valid values are within the range [0, 1].

Type: double

Default: 0.1

DDX_FMM_LOCAL_LMAX ¶

Maximal degree of local spherical harmonics (near-field FMM interations).

Type: integer

Default: 6

DDX_FMM_MULTIPOLE_LMAX ¶

Maximal degree of multipole spherical harmonics (far-field FMM interactions). Using the same value as DDX_LMAX is recommended and done by default.

Type: integer

Default: 9

DDX_FMM ¶

Use the fast multipole method to accelerate the solver

Type: boolean

Default: true

DDX_INCORE ¶

Use an in-core version, which uses more memory, but is generally faster

Type: boolean

Default: false

DDX_LOGFILE ¶

Logfile to dump a full trace of the DDX solver history for debugging.

Type: string

Default: No Default

DDX_SHIFT ¶

Shift for characteristic function of sphere overlap. Advanced parameter, which usually does not need to be modified. Valid values are within the range [-1, 1] with -100 denoting an automatic selection of the best shift.

Type: double

Default: -100.0

How to configure ddx for building Psi4¶

Role and Dependencies

Role — In PSI4, ddx is a library for providing fast continuum solvation models.
Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) ddx
Upstream Dependencies — ddx \(\Leftarrow\) Fortran

CMake Variables

ENABLE_ddx — CMake variable toggling whether Psi4 automatically installs ddx

Examples

Build and install ddx if needed

>>> cmake -DENABLE_ddx=ON

Build without ddx

>>> cmake