Merge pull request #167 from Becksteinlab/finalize-changes-070

updated CHANGES and other non-code for 0.7.0 release

.coveragerc

@@ -3,3 +3,5 @@ branch = True
 omit =
     # omit all tests
     mdpow/tests/*
+    mdpow/_version.py
+

.gitattributes

@@ -0,0 +1 @@
+mdpow/_version.py export-subst

.gitignore

@@ -10,4 +10,5 @@ __pycache__
 build
 dist
 doc/examples/benzene/Equilibrium/
-.coverage
+.coverage
+coverage.xml

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: doc/sphinx/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+   version: 2.7
+   install:
+   - requirements: doc/requirements.txt
+   system_packages: true

CHANGES

@@ -5,53 +5,77 @@ CHANGES for MDPOW
 Add summary of changes for each release. Use ISO dates. Reference
 GitHub issues numbers and PR numbers.
 
-2021-xx-xx    0.7.0
+2021-07-xx    0.7.0
 orbeckst, VOD555, ALescoul
 
+Changes
+
 * renamed package to MDPOW
-* tested with GROMACS 4.6.5, 2018.6, 2020.6, 2021.1 (PR #159, #164)
 * removed all generated docs from package
 * config parser MERGES user runinput.yml with the package defaults
   (#8)
-* boxtype and minimum distance (#30) can be set in runinput.yml and are
-  documented (#91, #88)
-* fixed: buffering kwarg was removed from openany() so code is
-  compatible with GromacsWrapper >= 0.8.0 (#107)
-* supported CHARMM and AMBER forcefield (#104)
-* supported wet-octanol solvent boxtype (#98)
-* fixed: using new travis CI settings so CI tests stop failing (#101)
-* fixed: GROMACS 2020 fails with "Inconsistency in user input:
-  Could not do a restart with appending because the checkpoint file was not
-  found. Either supply the name of the right checkpoint file or do not use
-  -append": mdpow.run.runMD_or_exit() does not anymore add -append to GROMACS
-  invocation (#128)
 * Configuration setting mdrun.maxthreads now also applies to energy
   minimization with mdpow-equilibrium.py/mdpow.run() (#119)
-* supported forcefield options in scripts (#123)
-* supported multiple edr files input in fep.py (#132)
-* supported alchemlyb estimators in analysis functions and scripts
-  (#133 #135)
-* fixed: return fig in fep.py so plot function in scripts can access the
-  object (#129)
-* support opls-aa tip4pd, amber tip4pew and cyclohexane, and charmm TIP5P
-  and cyclohexane solvent type (#141)
-* updated MDP templates:
+* Default plot option is now "none" for the mdpow-* scripts (PR #142)
+* Default estimator for mdpow analysis scripts is now alchemlyb MBAR
+  (#139, PR #142)
+* mdpow analysis scripts now default to statistical inefficiency
+  calculation (--SI) and stride=1 (#139, PR #142)
+* updated bundled CHARMM/CGENFF with charmm36-mar2019 (previously was
+  charmm36-jul2017)
+* removed deprecated -DFLEXIBLE grompp preprocessor flag from
+  em_opl.mdp template file
+* updated MDP templates (PR #155):
   - add files for AMBER (same as OPLS) and CHARMM for em, NPT, and bar (FEP)
     stages
-  - explicitly set "cutoff-scheme = verlet" in all MDP files; for GROMACS
-    4.6.5 FEP will fail with a FATAL ERROR "The Verlet cut-off scheme
+  - NOTE: explicitly set "cutoff-scheme = verlet" in all MDP files;
+    for GROMACS 4.6.5 FEP will fail with a FATAL ERROR "The Verlet cut-off scheme
     does not (yet) support free-energy calculations with perturbed
     atoms, only perturbed interactions." so you need to set the
     cutoff-scheme to the value "group".
   - disable energy group calculation to allow running on GPUs with
     modern GROMACS versions (such as 2021)
-  - use standard CHARMM non-bonded parameters for em_charmm.mdp
-    (for energy minimization)
   - added comments regarding GROMACS bug
     https://gitlab.com/gromacs/gromacs/-/issues/3403 that requires
     manually increasing rlist >= solute diameter
   - added comment regarding 'pme_order = 6' preventing PME calculation
     on GPUs with GROMACS 2021.
+* store version information in mdpow.__version__ instead of VERSION
+  get_version() (#165)
+
+Enhancements
+
+* tested with GROMACS 4.6.5, 2018.6, 2020.6, 2021.1 (PR #159, #164)
+* tested on Linux and and macOS (PR #159, #164)
+* supported CHARMM and AMBER forcefield, including PRM parameter files
+  with the "setup.prm" parameter in the configuration file (#104)
+* supported wet-octanol mixed solvent boxtype but this only works with
+  GROMACS >= 2018 (#98)  
+* support OPLS-AA TIP4PD, AMBER TIP4PEW and cyclohexane, and CHARMM TIP5P
+  and cyclohexane solvent types (#141)
+* supported forcefield options in scripts (#123)
+* supported multiple edr files input in fep.py (#132)
+* supported alchemlyb estimators (MBAR and TI) in analysis functions
+  and scripts (#133 #135)
+* boxtype and minimum distance (#30) can be set in runinput.yml and are
+  documented (#91, #88)
+* can now set fep.setup.maxwarn in config file (#113)
+
+Fixes
+
+* fixed: return fig in fep.py so plot function in scripts can access the
+  object (#129)
+* fixed: buffering kwarg was removed from openany() so code is
+  compatible with GromacsWrapper >= 0.8.0 (#107)
+* fixed: GROMACS 2020 fails with "Inconsistency in user input:
+  Could not do a restart with appending because the checkpoint file was not
+  found. Either supply the name of the right checkpoint file or do not use
+  -append": mdpow.run.runMD_or_exit() does not anymore add -append to GROMACS
+  invocation (#128)
+* fixed mdpow-pow and mdpow-pcw scripts (#138)  
+* fixed template em_charmm.mdp to use standard CHARMM non-bonded parameters
+  for energy minimization (PR #155)
+
 
 2017-05-02    0.6.1
 orbeckst, iorga, ianmkenney, rhheilma

MANIFEST.in

@@ -3,3 +3,5 @@ recursive-include   doc *.html *.css *.js *.txt *.inv *.png
 graft     mdpow/templates/
 graft     mdpow/top/
 graft     mdpow/top/oplsaa.ff/
+include versioneer.py
+include mdpow/_version.py

doc/requirements.txt

@@ -0,0 +1,8 @@
+six
+numpy
+scipy
+pandas
+pyyaml
+GromacsWrapper>=0.5.1
+alchemlyb
+mdanalysis<2

doc/sphinx/source/conf.py

@@ -11,20 +11,29 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import datetime
+# https://sphinx-rtd-theme.readthedocs.io/en/stable/
+import sphinx_rtd_theme
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+# make sure sphinx always uses the current branch
+sys.path.insert(0, os.path.abspath('../../..'))
 
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 # 'sphinx.ext.pngmath', 'sphinx.ext.jsmath'
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
-              'sphinx.ext.coverage', 'sphinx.ext.mathjax']
+              'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
+              'sphinx_rtd_theme']
+
+mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -40,14 +49,15 @@
 
 # General information about the project.
 project = u'MDPOW'
-copyright = u'2010–2021, Shujie Fan, Ian Kenney, Alia Lescoulie, Bogdan Iorga, and Oliver Beckstein'
+now = datetime.datetime.now()
+copyright = u'2010–{}, Shujie Fan, Ian Kenney, Alia Lescoulie, Bogdan Iorga, and Oliver Beckstein'.format(now.year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# Dynamically calculate the version based on mdpow.VERSION.
-packageversion = __import__('mdpow.version').get_version()
+# Dynamically calculate the version
+packageversion = __import__('mdpow').__version__
 
 # The short X.Y version.
 version = '.'.join(packageversion.split('.')[:2])
@@ -92,27 +102,31 @@
 #modindex_common_prefix = []
 
 
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'alabaster'
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
 html_theme_options = {
-    'github_user': 'Becksteinlab',
-    'github_repo': 'mdpow',
-    'description': "Solvation free energy calculations made easy.",
-    'travis_button': False,
-    'sidebar_includehidden': True,
-    'sidebar_collapse': True,
-    'show_related': True,
+    'canonical_url': '',
+    #'logo_only': True,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    'style_nav_header_background': 'white',
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False,
 }
 
+
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [
+    sphinx_rtd_theme.get_html_theme_path()
+]
+
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -137,22 +151,14 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'relations.html',
-        'searchbox.html',
-        'donate.html',
-    ]
-}
+#html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -218,10 +224,10 @@
 
 # Options for ext.intersphinx
 # ---------------------------
-# intersphinx: reference standard lib and GromacsWrapper
+# intersphinx: reference standard lib and RecSQL
 # http://sphinx.pocoo.org/latest/ext/intersphinx.html
 intersphinx_mapping = {'https://docs.python.org/': None,
-                       'https://docs.scipy.org/doc/numpy/': None,
+                       'https://numpy.org/doc/stable/': None,
                        'https://docs.scipy.org/doc/scipy/reference/': None,
                        'https://gromacswrapper.readthedocs.org/en/latest/': None,
                    }
@@ -235,3 +241,5 @@
 # This value selects what content will be inserted into the main body of an autoclass directive.
 # "class", "init", "both"
 autoclass_content = "both"
+
+

doc/sphinx/source/index.txt

@@ -87,6 +87,45 @@ small molecule (e.g. from LigandBook_ or ParamChem_).
 
 
 
+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:`gromacs.__version__`.
+
+.. autodata:: gromacs.__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 alabaster
 .. Contents:
 

mdpow/__init__.py

@@ -6,11 +6,13 @@
 
 from __future__ import absolute_import
 
-from .version import VERSION, get_version, get_version_tuple
 from . import log
 
-__all__ = ['fep', 'equil']
+from ._version import get_versions
+__version__ = get_versions()['version']
+del get_versions
 
+__all__ = ['fep', 'equil']
 
 def create_logger(logfile="mdpow.log"):
     """Create the default logger.
@@ -25,7 +27,7 @@ def create_logger(logfile="mdpow.log"):
 
 def log_banner():
     """Log program name and licence at INFO level."""
-    logger.info("MDPOW %s starting.", get_version())
+    logger.info("MDPOW %s starting.", __version__)
     logger.info("Copyright (c) 2010-2021 Shujie Fan, Ian Kenney, Alia Lescoulie, Bogdan Iorga, and Oliver Beckstein")
     logger.info("Released under the GNU Public Licence, version 3.")
     logger.info("For bug reports and help: https://github.com/Becksteinlab/MDPOW/issues")