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

Code author: Michael F. Herbst

Section author: Michael F. Herbst

Module: Keywords, PSI Variables

https://img.shields.io/badge/home-ddx-informational.svg
https://img.shields.io/badge/docs-latest-5077AB.svg

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

  • https://anaconda.org/conda-forge/pyddx/badges/version.svg
  • https://img.shields.io/pypi/v/pyddx
  • 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

  • https://img.shields.io/github/tag-date/ddsolvation/ddx.svg?maxAge=2592000
  • 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

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

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

DDX_INCORE

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

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

  1. Build and install ddx if needed

>>> cmake -DENABLE_ddx=ON
  1. Build without ddx

>>> cmake