=====================
Dispersion descriptor
=====================

The universal quantitative dispersion descriptor
:footcite:`pollice_universal_2019` can be calculated either approximately based
on tabulated vdW radii, or more accurately based on computed electron density
isosurfaces. Dispersion is modelled with the D3
:footcite:`grimme_consistent_2010` or D4 :footcite:`caldeweyher_extension_2017`
methods (the latter requires an external program).

***************
Preparing input
***************

There are two options for using surfaces based on the electron density.

####
Cube
####

Electron density in Gaussian cube format. Cube files can be generated by
various quantum-chemical programs, including Gaussian_.

########
Multiwfn
########

Exported surface from the `Multiwfn program`_ generated with the surface
analysis module (option 12 in the main menu). After generating the surface, it
should be exported to a file using the hidden option 66. This generates a file,
"vtx.pdb" that can be read by ᴍᴏʀғᴇᴜs. For more information, see Section 3.15.4
of the `Multiwfn manual`_.

******
Module
******

The Dispersion class is provided to calculate and store the dispersion
descriptors.

.. code-block:: python
  :caption: Example

  >>> elements, coordinates = read_geometry("corannulene.xyz")
  >>> disp = Dispersion(elements, coordinates)
  >>> disp.print_report()
  Surface area (Ų): 284.6
  Surface volume (ų): 290.0
  P_int (kcal¹ᐟ² mol⁻¹ᐟ²): 20.8
  >>> disp.atom_p_int[1]
  30.19400992973631

By default, the molecular surface is constructed from vdW spheres and an
internal D3 code is used. The choice of vdW radii can be changed from the
default of ``rahm`` with ``radii_type=<str>``. Custom radii can be supplied
with ``radii=<list>``. Density of points on the vdW surface is controlled with
``density=<float>``. Dispersion coefficients can be read from the output of
Grimme's D3 and D4 programs with the
:py:meth:`load_coefficients <morfeus.dispersion.Dispersion.load_coefficients>`
method. To suppress the internal D3 code, set ``calculate_coefficients=False``
appropriately. To use another surface, suppress the vdW surface creation with
``point_surface=False`` and use the
:py:meth:`surface_from_cube <morfeus.dispersion.Dispersion.surface_from_cube>`
or
:py:meth:`surface_from_multiwfn <morfeus.dispersion.Dispersion.surface_from_multiwfn>` methods.

.. code-block:: python
  :caption: Example with external cube and coefficients files

  >>> elements, coordinates = read_xyz("corannulene.xyz")
  >>> disp = Dispersion(elements, coordinates, point_surface=False)
  >>> disp.load_coefficients("d4_corannulene", "d4")
  >>> disp.surface_from_cube("corannulene.cub")
  >>> disp.compute_p_int()
  >>> disp.print_report()
  Surface area (Ų): 248.0
  Surface volume (ų): 247.8
  P_int (kcal¹ᐟ² mol⁻¹ᐟ²): 27.2
  >>> disp.atom_p_int[1]
  40.907980526799534

To exclude atoms from the calculation, the atom indices (starting at 1) should
be provided with ``excluded_atoms=<list>``. This can for example be used to
calculate substitutent P_int values.

Grimme's `dftd4 program`_ can be used to calculate the dispersion coefficients
with the D4 method. The accompanying dftd4 python package must also be
installed in the same Python environment as Morfeus. An example is given below:

.. code-block:: python
  :caption: Example with Grimme's dftd4 code

  >>> elements, coordinates = read_xyz("pme3.xyz")
  >>> disp = Dispersion(elements, coordinates, compute_coefficients=False)
  >>> disp.compute_coefficients(model="gd4")
  >>> disp.compute_p_int()
  >>> disp.print_report()
  Surface area (Ų): 178.4
  Surface volume (ų): 157.8
  P_int (kcal¹ᐟ² mol⁻¹ᐟ²): 20.1

The D4 model is available with 'gd4' and the internal D3 code with 'id3'. The
maximum order of the dispersion coefficients can be set with the keyword
argument 'order', but should be left by the non-expert user at the default
setting of 8 (*i.e.* C\ :sub:`6` and C\ :sub:`8`)

For more detailed information, use ``help(Dispersion)`` or see the API:
:py:class:`Dispersion <morfeus.dispersion.Dispersion>`

.. note::

  Use the command line flag ``--molc6`` to get the dftd4 program to print the
  dispersion coefficients.

*******************
Command line script
*******************

The command line script provides access to the basic functionality through
the terminal.

.. code-block:: shell
  :caption: Example

  $ morfeus dispersion tBu.xyz - - print_report
  Surface area (Ų): 142.6
  Surface volume (ų): 121.2
  P_int (kcal¹ᐟ² mol⁻¹ᐟ²): 13.2

**********
Background
**********

The 🍺P\ :sub:`int` dispersion descriptor was introduced by Pollice and Chen as
a quantitative descriptor for dispersion interactions
:footcite:`pollice_universal_2019`. ᴍᴏʀғᴇᴜs can calculate P\ :sub:`int` based
on an electron density isosurface, as in the original article. In addition, we
have found that a very fast method based on surfaces constructed from vdW radii
correlate well with P\ :sub:`int` from electron densities, at a fraction of the
cost.

.. todo::
  add figure here benchmarks/local_force/benchmark.png

.. footbibliography::

.. _dftd4 program: https://github.com/grimme-lab/dftd4
.. _Gaussian: https://gaussian.com/cubegen/
.. _Multiwfn program: http://sobereva.com/multiwfn/
.. _Multiwfn manual: http://sobereva.com/multiwfn/Multiwfn_manual.html