# 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],
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**

## 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 PCM can only be used for energy calculations with SCF
wavefunctions in the PTE approximation [Cammi:2009:164104].
All ERI algorithms (`PK`

, `OUT_OF_CORE`

, `DIRECT`

, `DF`

, `CD`

) are supported.

Note

linear response calculations (static polarisabilities, TD-SCF) are supported for RHF/UHF if available.

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`