.. MDpow documentation master file, created by
   sphinx-quickstart on Wed Mar 24 13:28:55 2010.

.. Common replacements for MDPOW docs
.. |Pow| replace:: *P*\ :sub:`OW`
.. |P_OW| replace:: *P*\ :sub:`OW`
.. |POW|  replace:: *P*\ :sub:`OW`
.. |P_ow| replace:: *P*\ :sub:`OW`
.. |P_cw| replace:: *P*\ :sub:`CW`
.. |P_tw| replace:: *P*\ :sub:`TW`


MDPOW documentation
===================

:Release: |release|
:Date: |today|


**MDPOW** is a python package that automates the calculation of
solvation free energies via molecular dynamics (MD) simulations. In
particular, it facilitates the computation of partition
coeffcients. Currently implemented:

- *water-octanol* partition coefficient (|P_ow|)
- *water-cyclohexane* partition coefficient (|P_cw|)
- *water-toluene* partition coefficient (|P_tw|)
  
The package is being actively developed and incorporates recent ideas
and advances. If something appears unclear or just wrong, then please
ask questions on the `MDPOW Issue Tracker`_.

.. _`MDPOW Issue Tracker`: https://github.com/Becksteinlab/mdpow/issues


.. _supported-versions:

MD engine
---------

Calculations are performed with the Gromacs_ molecular dynamics (MD)
software package [#GromacsWrapperFramework]_. MDPOW is tested with

* Gromacs 4.6.5
* Gromacs 2018.6
* Gromacs 2020.6
* Gromacs 2021.1
* Gromacs 2022.4 
* Gromacs 2023.1 

but versions 5.x, 2016.x, and 2019.x should also work.
It should be possible to use any of these Gromacs versions without
further adjustments, thanks to the underlying GromacsWrapper library
[#GromacsWrapperFramework]_.

Nevertheless, you should *always* check the topology and runinput
(mdp) files for the version of Gromacs_ that you are using.


Force fields
------------

Currently

* OPLS-AA
* CHARMM/CGenFF
* AMBER/GAFF

are supported. In principle it is possible to add force fields sets by
changing the :envvar:`GMXLIB` environment variable and providing
appropriate template files but this is currently untested.

A number of different *water models* are supporte (see
:data:`mdpow.forcefields.GROMACS_WATER_MODELS`).

.. seealso:: :mod:`mdpow.forcefields`


Required input
--------------

As *input*, the user only needs to provide a structure file (PDB or
GRO) and a Gromacs ITP file containing the parametrization of the
small molecule (e.g. from LigandBook_ or ParamChem_).

.. _Gromacs: http://www.gromacs.org
.. _GromacsWrapper: http://gromacswrapper.readthedocs.org/en/latest/
.. _LigandBook: http://ligandbook.icsn.cnrs-gif.fr/
.. _ParamChem: https://cgenff.paramchem.org/



Version information
-------------------

MDPOW uses `semantic versioning`_ with the release number consisting
of a triplet *MAJOR.MINOR.PATCH*. *PATCH* releases are bug fixes or
updates to docs or meta data only and do not introduce new features or
change the API. Within a *MAJOR* release, the user API is stable
except during the development cycles with MAJOR = 0 where the API may
also change (rarely) between MINOR releases. *MINOR* releases can
introduce new functionality or deprecate old ones.

The version information can be accessed from the attribute
:data:`mdpow.__version__`.
      
.. autodata:: mdpow.__version__

.. _semantic versioning: https://semver.org	      

Limitations and known issues
----------------------------

For current issues and open feature requests please look through the
`MDPOW Issue Tracker`_. Some of the major open issues are:

* GROMACS versions < 2021 can silently produce incorrect free energy estimates because exclusions
  are not properly accounted for 
  for solutes larger than the rlist cutoff when the ``couple-intramol = no`` decoupling is used
  (as it is in all of MDPOW), see https://gitlab.com/gromacs/gromacs/-/issues/3403.
  MDPOW does not detect this situation and does not offer a workaround (namely doing separate 
  vacuum simulations and use ``couple-intramol = yes``). GROMACS 2021 at least fails when the
  failure condition occurs (see https://gitlab.com/gromacs/gromacs/-/merge_requests/861).
* Only free energy calculations of neutral solutes are supported; the workflow also does not 
  include addition of ions (see issue `#97 <https://github.com/Becksteinlab/MDPOW/issues/97>`_).
* Mixed solvents (octanol and water) are only supported with the included template topology files
  for GROMACS >= 2018.
* Adding new solvents requires modifying the MDPOW code; instead it should be configurable.



.. Hide to use with RTD theme
.. Contents:

.. toctree::
   :maxdepth: 4
   :numbered:
   :hidden:

   INSTALL
   init
   scripts
   equil
   fep
   analysis
   workflows
   utilities
   forcefields

.. rubric:: Indices and tables

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. rubric:: Footnotes

.. [#GromacsWrapperFramework] The package is built on top of the `GromacsWrapper`_
                     framework (which is automatically installed).