# 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

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] and the polarisable continuum model (PCM) [Tomasi:2005:2999] [Nottoli:2019:6061] 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",
})

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


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.

### DDX¶

DDX boolean for ddx module

### DDX_MODEL¶

Switch available solvation models

• Type: string

• Possible Values: PCM, COSMO

• Default: PCM

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

• Type: array

• Default: No Default

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

• Type: double

• Default: 1.1

• 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

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

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