From 0124569845080456f40a02c718dacfe5ebd69c08 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Wed, 4 Aug 2021 15:37:45 -0700 Subject: [PATCH 1/4] doc updates - added section on run input file - added warning to forcefields for choice of water model - fixed energies.txt example in docs - minor reST fixes (e.g. use raw strings for mathjax) - new examples/README.rst to explain what to do with the example files (also *ran* everything in Python 3.8 and GROMACS 2019 to check that it actually works) Co-authored-by: Bogdan I. Iorga --- doc/examples/README.rst | 139 ++++++++++++++++++++++++++++++++++ doc/sphinx/source/scripts.txt | 106 +++++++++++++++----------- mdpow/forcefields.py | 19 ++++- 3 files changed, 215 insertions(+), 49 deletions(-) create mode 100644 doc/examples/README.rst diff --git a/doc/examples/README.rst b/doc/examples/README.rst new file mode 100644 index 00000000..94a24330 --- /dev/null +++ b/doc/examples/README.rst @@ -0,0 +1,139 @@ +.. -*- coding: utf-8 -*- + +======================== + MDPOW Example: Benzene +======================== + +The ``examples`` directory contains input file for the solvation free +energy calculation of benzene in solvent (water and octanol), using +the OPLS-AA force field and the TIP4P water model. + +There are two ways to use MDPOW: + +1. commandline interface (CLI) through scripts +2. Python API + + +The online documentation goes into greater details. This README just +gives the briefest of summaries. + + + +Included files +============== + +The files in the examples directory are :: + + benzene.yml + benzene/ + ├── README.txt + ├── benzene.itp + ├── benzene.pdb + ├── benzene.pdb.png + ├── dVdl.pdf + └── session.py + +Run input file ``benzene.yml`` +------------------------------ + +For running the simulations with the CLI, the run input file +``benzene.yml`` and the GROMACS input files ``benzene/benzene.itp`` +and ``benzene/benzene.pdb`` are needed. The path to these files is +already in the runinput file so leave all files in place. + + +Benzene directory +----------------- + +The ``benzene`` directory contains input files for GROMACS + +* ``benzene.pdb``: coordinates in PDB format +* ``benzene.itp``: topology and parameters + +an image of the chemical structure ``benzene.pdb.png``, output from +plotting dH/dlambda (for the MDPOW TI estimator) ``dVdl.pdf`` for +benzene in water. + +The ``README.txt`` file explains how to try out the Python API, with +the commands recorded in ``session.py``. + + + +Using the CLI +============= + +Make sure that GROMACS commands can be run (e.g., ``source GMXRC`` or +``module load gromacs``). All commands are run from the directory that +contains the run input file ``benzene.yml``. + +To calculate the water solvation free energy:: + + mdpow-equilibrium --solvent water benzene.yml + mdpow-fep --solvent water benzene.yml + mdpow-solvationenergy --solvent water benzene + +See output in file ``energies.txt`` where all energies are in kJ/mol:: + + ITP mol solvent dG err_dG Coulomb err_Cou VDW err_VDW directory + ---------- ---------------- ------ -------- --------- -------- --------- -------- --------- + BNZ water -8.32 1.49 +7.53 0.51 +0.78 1.40 benzene + + +To calculate the octanol solvation free energy:: + + mdpow-equilibrium --solvent octanol benzene.yml + mdpow-fep --solvent octanol benzene.yml + mdpow-solvationenergy --solvent octanol benzene + +The octanol energies are appended to the ``energies.txt`` file:: + + BNZ water -8.32 1.49 +7.53 0.51 +0.78 1.40 benzene + BNZ octanol -17.03 1.24 +1.93 0.25 +15.10 1.22 benzene + +Based on these *very* short simulations, the solvation free energy of benzene +in water of -8.32±1.49 kJ/mol is less favorable than the solvation free energy +in octanol of –17.03±1.24 kJ/mol. + +Using these numbers, one can directly calculate the water-octanol partition +coefficient as + +.. math:: + + \log P_{OW} = (\Delta G_W - \Delta G_O)/kT \log e + +or use a script :: + + mdpow-pow benzene/ + +which outputs :: + + mdpow.fep : INFO [BNZ] Free energy of transfer water --> octanol: -8.712 (1.941) kJ/mol + mdpow.fep : INFO [BNZ] log P_ow: 1.517 (0.338) + +and appends a line to the file ``pow.txt`` with content :: + + + ITP mol transferFE error logPow err_logPow directory + ---------- --------- ------ ------ -------- ---------- --------- + BNZ -8.71 1.94 logPow +1.52 0.34 benzene + +(It also writes output to ``energies.txt``. See online docs.) + +Instead of running ``mdpow-solvationenergy`` for different solvents, +one can also just run ``mdpow-pow DIRECTORY`` and it will run the +separate free energy calculations automatically and then compute the +octanol-water partition coefficient. + + +The example CLI runs execute GROMACS immediately and run the FEP calculations +serially. For production calculations you will likely want to run these in +parallel on a computer cluster or HPC. The online documentation explains how to +change the runinput file to stop at various steps instead of running MD +simulations immediately. + + +Using the Python API +==================== + +See the ``benzene/README.txt`` and ``benzene/session.py`` files as well as the +online documentation. diff --git a/doc/sphinx/source/scripts.txt b/doc/sphinx/source/scripts.txt index fb40c05b..630ee9d4 100644 --- a/doc/sphinx/source/scripts.txt +++ b/doc/sphinx/source/scripts.txt @@ -36,6 +36,49 @@ input file (see `Equilibrium simulations`_) is the value of the variable ``name`` in the ``[setup]`` section. +.. _runinput-file: + +Run input file +-------------- + +The ``mdpow-*`` scripts are the **commandline interface** (CLI) to the +Python API functionality in the :mod:`mdpow` package. Whereas the +Python API requires passing of parameters to classes and functions and +therefore exposes the full flexibility of MDPOW, the CLI works with a +narrower set of options which are collected in a **run input +file**. This run input file or *RUNFILE* is named :file:`runinput.yml` +by default. + +A template *RUNFILE* can be generated with +:program:`mdpow-get-runinput` + +.. code-block:: bash + + mdpow-get-runinput runinput.yml + +which will copy the default run input file bundled with MDPOW and put +it in the current directory under the name :file:`runinput.yml`. + +For an example of a *RUNFILE* see :download:`benzene.yml +<../../examples/benzene.yml>`. The comments in the file serve as the +documentation. + +The run input file uses `YAML`_ syntax (and is parsed by :mod:`yaml`). + +.. Note:: + + It is recommended to use absolute paths to file names. + +.. Note:: + + It is recommended to enclose all strings in the input file in + quotes, especially if they can be interpreted as numbers. For + example, a name "005" would be interpreted as the number 5 unless + explicitly quoted. + +.. _YAML: http://yaml.org/ + + .. _mdpow-equilibrium-label: Equilibrium simulations @@ -50,10 +93,10 @@ The :program:`mdpow-equilibrium` script :program:`mdrun` herself (e.g. on a cluster) or let the script do it locally on the workstation -The script runs essentially the same steps as described in the tutorial -:ref:`example_octanol-label` but it gathers all required parameters from a run -input file and it allows one to stop and continue and the protocol -transparently. +The script runs essentially the same steps as described in the +tutorial :ref:`example_octanol-label` but it gathers all required +parameters from the :ref:`run input file` and it allows +one to stop and continue and the protocol transparently. It requires as at least Gromacs 4.6.5 ready to run (check that all commands can be found). The required **input** is @@ -62,23 +105,6 @@ be found). The required **input** is 2. a structure file (PDB or GRO) for the compound 3. a Gromacs ITP file for the compound (OPLS/AA force field) -A template *RUNFILE* can be generated with :program:`mdpow-get-runinput` -``runinput.yml``, which will copy the default run input file bundled with -MDPOW and put it in the current directory under the name -``runinput.yml``. - -For an example of a *RUNFILE* see :download:`benzene.yml -<../../examples/benzene.yml>`. It is recommended to use absolute paths -to file names. The run input file uses `YAML`_ syntax (and is parsed -by :mod:`yaml`). - -.. _YAML: http://yaml.org/ - -.. Note:: It is recommended to enclose all strings in the input file - in quotes, especially if they can be interpreted as - numbers. For example, a name "005" would be interpreted as - the number 5 unless explicitly quoted. - The script keeps track of the stages of the simulation protocol (in the state files :file:`water.simulation`, :file:`octanol.simulation` etc) and allows the user to **restart from the last completed @@ -141,7 +167,7 @@ input file. You will require: -1. at least Gromacs 4.0.5 ready to run (check that all commands can +1. at least Gromacs 4.6.5 ready to run (check that all commands can be found) 2. the results from a previous complete run of :program:`mdpow-equilibrium` @@ -590,16 +616,6 @@ compounds as above. error on **VDW** -**Vdp** - - correction if the FEP are run at constant volume but the - desired solvation free energy is the Gibbs energy (**currently - neglected** and set to 0) - -**errVdp** - - error on **Vdp** - **w2oct** transfer free energy from water to octanol (difference between @@ -627,19 +643,19 @@ compounds as above. .. _table-energies-label: .. Table:: Solvation free energies for compounds in water and octanol (in kJ/mol). - - ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== - molecule solvent DeltaG0 errDG0 coulomb errCoul VDW errVDW Vdp errVdp w2oct errw2oct logPOW errlogP directory - ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== - BNZ water -2.97 0.21 +7.65 0.07 -4.68 0.20 +0.00 0.00 -12.87 0.43 +2.24 0.07 benzene - BNZ octanol -15.84 0.37 +1.40 0.19 +14.44 0.32 +0.00 0.00 -12.87 0.43 +2.24 0.07 benzene - OC9 water -16.03 0.32 +27.35 0.09 -11.32 0.31 +0.00 0.00 -16.24 1.12 +2.83 0.20 octanol - OC9 octanol -32.28 1.08 +11.32 0.92 +20.96 0.56 +0.00 0.00 -16.24 1.12 +2.83 0.20 octanol - URE water -53.52 0.17 +56.94 0.11 -3.41 0.14 +0.00 0.00 +4.66 1.13 -0.81 0.20 urea - URE octanol -48.86 1.12 +35.75 1.09 +13.11 0.25 +0.00 0.00 +4.66 1.13 -0.81 0.20 urea - 902 water -25.46 0.11 +34.93 0.10 -9.48 0.06 +0.00 0.00 +9.35 1.06 -1.63 0.18 water_TIP4P - 902 octanol -16.11 1.05 +21.16 1.05 -5.05 0.09 +0.00 0.00 +9.35 1.06 -1.63 0.18 water_TIP4P - ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== + + ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== + molecule solvent DeltaG0 errDG0 coulomb errCoul VDW errVDW w2oct errw2oct logPOW errlogP directory + ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== + BNZ water -2.97 0.21 +7.65 0.07 -4.68 0.20 -12.87 0.43 +2.24 0.07 benzene + BNZ octanol -15.84 0.37 +1.40 0.19 +14.44 0.32 -12.87 0.43 +2.24 0.07 benzene + OC9 water -16.03 0.32 +27.35 0.09 -11.32 0.31 -16.24 1.12 +2.83 0.20 octanol + OC9 octanol -32.28 1.08 +11.32 0.92 +20.96 0.56 -16.24 1.12 +2.83 0.20 octanol + URE water -53.52 0.17 +56.94 0.11 -3.41 0.14 +4.66 1.13 -0.81 0.20 urea + URE octanol -48.86 1.12 +35.75 1.09 +13.11 0.25 +4.66 1.13 -0.81 0.20 urea + 902 water -25.46 0.11 +34.93 0.10 -9.48 0.06 +9.35 1.06 -1.63 0.18 water_TIP4P + 902 octanol -16.11 1.05 +21.16 1.05 -5.05 0.09 +9.35 1.06 -1.63 0.18 water_TIP4P + ========== ========== ======== ======== ======== ======== ======== ======== ======== ======== ======== ======== ==================== House-keeping scripts diff --git a/mdpow/forcefields.py b/mdpow/forcefields.py index 61118919..7d5678ee 100644 --- a/mdpow/forcefields.py +++ b/mdpow/forcefields.py @@ -37,7 +37,9 @@ .. autodata:: SPECIAL_WATER_COORDINATE_FILES .. autodata:: GROMACS_WATER_MODELS + :noindex: .. autodata:: GROMACS_SOLVENT_MODELS + :noindex: Internal classes and functions ------------------------------ @@ -61,8 +63,9 @@ import logging logger = logging.getLogger("mdpow.forecefields") -#: Default force field. At the moment, only OPLS-AA is directly -#: supported. +#: Default force field. At the moment, OPLS-AA, CHARMM/CGENFF, and AMBER/GAFF +#: are directly supported. However, it is not recommended to change the +#: default here as this behavior is not tested. DEFAULT_FORCEFIELD = "OPLS-AA" #------------------------------------------------------------ @@ -127,8 +130,16 @@ def _create_water_models(watermodelsdat): description=description) return models -#: Use the default water model unless another water model is chosen in the runinput -#: file (``setup.watermodel``). +#: Use the default water model unless another water model is chosen in the +#: :ref:`run input file ` file by setting the +#: ``setup.watermodel`` parameter. +#: +#: .. warning:: +#: Select the native water model **manually** and do not rely on the default +#: set here. For CHARMM/GAFF the CHARMM TIP3P model is recommended. +#: For AMBER/GAFF the TIP3P mdeol is often used. Choosing the correct water model +#: is a *scientific* decision that *you* have to make conscientiously. +#: DEFAULT_WATER_MODEL = "tip4p" #: Dictionary of :class:`GromacsSolventModel` instances, one for each Gromacs water From 020fc1a903d707972865ba778be579595371ca49 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Wed, 4 Aug 2021 16:15:41 -0700 Subject: [PATCH 2/4] update CHANGES for 0.7.1 --- CHANGES | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 6124c2a6..6e24f024 100644 --- a/CHANGES +++ b/CHANGES @@ -6,8 +6,8 @@ Add summary of changes for each release. Use ISO dates. Reference GitHub issues numbers and PR numbers. -2021-xx-xx 0.7.1 -orbeckst +2021-08-04 0.7.1 +orbeckst, iorga Fixes @@ -19,6 +19,7 @@ Fixes error like "results.DeltaA does not contain 'Gibbs'") (PR #185) * ensure that pickle files created under Python 2 are also readable under Python 3 +* documentation fixes (PR #176) 2021-08-02 0.7.0 From 7047b3da2e1d70ec267d7c6b16baf666d2db3f7f Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Thu, 5 Aug 2021 02:31:46 -0700 Subject: [PATCH 3/4] switch RTD to Python 3.8 --- .readthedocs.yaml | 2 +- doc/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 34ece6a6..479fbf75 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,7 +15,7 @@ formats: # Optionally set the version of Python and requirements required to build your docs python: - version: 2.7 + version: 3.8 install: - requirements: doc/requirements.txt system_packages: true \ No newline at end of file diff --git a/doc/requirements.txt b/doc/requirements.txt index ee525a61..e487171e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,4 +5,4 @@ pandas pyyaml GromacsWrapper>=0.5.1 alchemlyb -mdanalysis<2 +mdanalysis From 84627595333246c441b62612bb3ee468d2d28405 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Thu, 5 Aug 2021 02:45:44 -0700 Subject: [PATCH 4/4] cleaner release printing in docs --- doc/sphinx/source/conf.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index 0620a585..6aa70864 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/sphinx/source/conf.py @@ -61,8 +61,23 @@ # The short X.Y version. version = '.'.join(packageversion.split('.')[:2]) + # The full version, including alpha/beta/rc tags. -release = packageversion +##release = packageversion +# +# clean up for RTD: +# 0.7.0+5.g8afad4b.dirty --> 0.7.0+5.g8afad4b +# 0.7.0+0.g43485dd.dirty --> 0.7.0 +try: + ver, rc = packageversion.split("+") +except ValueError: + ver, rc = packageversion, None + +if not rc or rc.startswith('0'): + release = ver +else: + release = ver + "+" + rc.replace(".dirty", "") + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages.