Merged fork with latest original master

docs-source/api-c++/render.py

+from __future__ import print_function
+import os
+import sys
+from functools import reduce
+from os.path import basename, dirname, join, splitext
+from glob import glob
+
+import jinja2
+import lxml.etree as ET
+
+
+def load_doxygen_xml(doxygen_xml):
+    files = [os.path.join(doxygen_xml, f)
+             for f in os.listdir(doxygen_xml)
+             if f.lower().endswith('.xml') and not f.startswith('._')]
+    if len(files) == 0:
+        raise err
+
+    document = ET.ElementTree(ET.Element('root')).getroot()
+    for file in files:
+        root = ET.parse(file).getroot()
+        for node in root:
+            document.append(node)
+    return document
+
+
+def subclasses(root, parent):
+    parent_el = root.xpath('.//compounddef/compoundname[text()="%s"]/..' % parent)
+    if len(parent_el) == 1:
+        parent_id = parent_el[0].get('id')
+    else:
+        raise ValueError("Can't find %s" % parent)
+
+    xp_query = ('.//compounddef/basecompoundref[@refid="%s"]'
+                '/../compoundname') % parent_id
+    return [parent] + [n.text.strip() for n in root.xpath(xp_query)]
+
+
+def allclasses(root):
+    xp_query = './/compounddef[@kind="class" and @prot="public"]/compoundname'
+    return [e.text for e in root.xpath(xp_query)]
+
+
+def template_data(root):
+    data = {
+        'core': ('OpenMM::System', 'OpenMM::Context', 'OpenMM::State', 'OpenMM::Platform'),
+        'forces': sorted(subclasses(root, 'OpenMM::Force')),
+        'integrators': sorted(subclasses(root, 'OpenMM::Integrator')),
+
+    }
+    data['extras'] = sorted(set(allclasses(root)) -
+                            reduce(set.union, map(set, data.values())))
+    return data
+
+
+def main():
+    if len(sys.argv) == 1:
+        print('usage: %s <doxygen_xml_path>' % sys.argv[0], file=sys.stderr)
+        exit(1)
+    doxygen_xml_path = sys.argv[1]
+
+    root = load_doxygen_xml(doxygen_xml_path)
+    data = template_data(root)
+
+    here = dirname(__file__)
+    templateLoader = jinja2.FileSystemLoader(here)
+    templateEnv = jinja2.Environment(loader=templateLoader)
+
+    for template_fn in map(basename, glob(join(here, '*.jinja2'))):
+        output_fn = splitext(template_fn)[0]
+        print('Rendering %s to %s...' % (template_fn, output_fn))
+
+        template = templateEnv.get_template(template_fn)
+        output_text = template.render(data)
+        with open(output_fn, 'w') as f:
+            f.write(output_text)
+
+
+if __name__ == '__main__':
+    main()

docs-source/api-python/CMakeLists.txt

+set(STAGING_OUTPUT_FILES "") # Will contain all required package files
+file(GLOB STAGING_INPUT_FILES RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}"
+    "app.rst.jinja2"
+    "library.rst.jinja2"
+    "index.rst"
+    "render.py"
+    "conf.py"
+    "process-docstring.py"
+    "_static/logo.png"
+    "_templates/class.rst"
+)
+
+foreach(INIT_FILE ${STAGING_INPUT_FILES})
+    set(infile "${CMAKE_CURRENT_SOURCE_DIR}/${INIT_FILE}")
+    set(outfile "${CMAKE_CURRENT_BINARY_DIR}/${INIT_FILE}")
+    add_custom_command(
+        OUTPUT "${outfile}"
+        COMMAND "${CMAKE_COMMAND}" -E copy_if_different "${infile}" "${outfile}"
+        DEPENDS "${infile}"
+        COMMENT "CMake-copying file ${infile} to ${outfile}")
+    set(STAGING_OUTPUT_FILES ${STAGING_OUTPUT_FILES} "${outfile}")
+endforeach(INIT_FILE ${STAGING_INPUT_FILES})
+
+
+add_custom_command(
+    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/app.rst"
+           "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+    COMMAND "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/app.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst.jinja2"
+            "${CMAKE_CURRENT_BINARY_DIR}/render.py"
+)
+
+add_custom_command(
+    OUTPUT "${CMAKE_BINARY_DIR}/api-python/index.html"
+    COMMAND "${PYTHON_EXECUTABLE}" -m sphinx . "${CMAKE_BINARY_DIR}/api-python"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/conf.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/process-docstring.py"
+            "${CMAKE_CURRENT_BINARY_DIR}/app.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/library.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/index.rst"
+            "${CMAKE_CURRENT_BINARY_DIR}/_static/logo.png"
+            "${CMAKE_CURRENT_BINARY_DIR}/_templates/class.rst"
+            # PythonInstall
+)
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/api-python/)
+add_custom_target(PythonApiDocs DEPENDS ${CMAKE_BINARY_DIR}/api-python/index.html)
+INSTALL(DIRECTORY "${CMAKE_BINARY_DIR}/api-python/"
+        DESTINATION "docs/api-python/")
+INSTALL(FILES "${CMAKE_CURRENT_SOURCE_DIR}/../Python API Reference.html"
+        DESTINATION "docs/")

docs-source/api-python/_templates/class.rst

+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs-source/api-python/app.rst.jinja2

+.. _app :
+
+Application Layer
+=================
+
+Loaders and Setup
+~~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+{% for fileclass in fileclasses %}
+    ~{{ fileclass }}
+{% endfor %}
+
+
+Representation and Manipulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    ~simtk.openmm.app.topology.Topology
+    ~simtk.openmm.app.topology.Chain
+    ~simtk.openmm.app.topology.Residue
+    ~simtk.openmm.app.topology.Atom
+    ~simtk.openmm.app.modeller.Modeller
+
+Simulation
+~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    ~simtk.openmm.app.forcefield.ForceField
+    ~simtk.openmm.app.simulation.Simulation
+
+
+Reporting Output
+~~~~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+{% for reporter in reporters %}
+    ~{{ reporter }}
+{% endfor %}
+
+
+Extras
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    {% for extra in app_extras %}
+    ~{{ extra }}
+    {% endfor %}
+
+Units
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for unit in units %}
+    ~{{ unit }}
+    {% endfor %}

docs-source/api-python/conf.py

+# -*- coding: utf-8 -*-
+
+import sys
+import os
+import simtk.openmm.version
+
+extensions = ['sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.autosummary',
+              'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'process-docstring',
+              'sphinxcontrib.lunrsearch']
+
+autosummary_generate = True
+autodoc_default_flags = ['members', 'inherited-members']
+autodoc_member_order = 'bysource'
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = u'OpenMM'
+copyright = u'2015, Stanford University and the Authors'
+
+version = simtk.openmm.version.short_version
+release = simtk.openmm.version.full_version
+
+exclude_patterns = ['_build', '_templates']
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+pygments_style = 'sphinx'
+
+html_theme = "alabaster"
+html_theme_options = {
+    'description': "High performance molecular simulation on GPUs",
+    'github_button': False,
+    # 'github_user': 'pandegroup',
+    # 'github_repo': 'openmm',
+    'logo_name': False,
+    'logo': 'logo.png',
+}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'searchbox.html',
+        'navigation.html',
+    ]
+}
+
+# Napoleon settings
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True

docs-source/api-python/index.rst

+.. currentmodule:: simtk.openmm.openmm
+
+OpenMM Python API
+=================
+
+The Python API provides information about the classes and methods available in OpenMM for Python developers.
+
+OpenMM consists of two parts. First, there is a set of :ref:`libraries <library>` for performing many types of computations needed for molecular simulations: force evaluation, numerical integration, energy minimization, etc.
+
+Second, there is an :ref:`application layer <app>`, a set of Python libraries providing a high level interface for running simulations. This layer is targeted at computational biologists or other people who want to run simulations, and who may or may not be programmers.
+
+See the user guide for more details.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   app
+   library

docs-source/api-python/library.rst.jinja2

+.. _library :
+
+Library Layer
+=============
+
+
+Core Objects
+~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    ~simtk.openmm.openmm.System
+    ~simtk.openmm.openmm.Context
+    ~simtk.openmm.openmm.Platform
+    ~simtk.openmm.openmm.State
+
+
+Forces
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for force in forces %}
+    ~{{ force }}
+    {% endfor %}
+
+
+Integrators
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for integrator in integrators %}
+    ~{{ integrator }}
+    {% endfor %}
+
+Extras
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+    :nosignatures:
+
+    {% for extra in library_extras %}
+    ~{{ extra }}
+    {% endfor %}

docs-source/api-python/process-docstring.py

+import re
+
+def process_docstring(app, what, name, obj, options, lines):
+    """This hook edits the docstrings to replace "<tt><pre>" html tags
+    with sphinx directives.
+    """
+    def repl(m):
+        s = m.group(1)
+        if not s.startswith(linesep):
+            s = linesep + s
+        newline = '.. code-block:: c++' + linesep
+        return newline + '    ' + s.replace(linesep, linesep + '    ')
+
+    if name == 'simtk.openmm.openmm.CustomTorsionForce':
+         print(lines)
+
+    linesep = '|LINEBREAK|'
+    joined = linesep.join(lines)
+
+    joined = re.sub(r'<tt><pre>((|LINEBREAK|)?.*?)</pre></tt>', repl, joined)
+    joined = re.sub(r'<tt>(.*?)</tt>', repl, joined)
+    lines[:] = [(l if not l.isspace() else '') for l in joined.split(linesep)]
+
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_docstring)
+
+
+def test():
+    lines    = ['Hello World', '<tt><pre>', 'contents', '</pre></tt>', '', '<tt>contents2</tt>']
+    linesRef = ['Hello World', '.. code-block:: c++', '', '    contents', '', '', '.. code-block:: c++', '', '    contents2']
+    process_docstring(None, None, None, None, None, lines)
+    assert lines == linesRef
+
+if __name__ == '__main__':
+    test()

docs-source/api-python/render.py

+"""
+The function of this script is to render the Jinja2 templates in the current
+directory into input files for sphinx. It introspects the OpenMM Python module
+to find all of the classes and formats them for inclusion into the templates.
+"""
+from os.path import dirname, join, splitext, basename
+from glob import glob
+import inspect
+
+import jinja2
+import simtk.openmm
+import simtk.openmm.app
+
+
+
+def fullname(klass):
+    return klass.__module__ + '.' + klass.__name__
+
+
+def library_template_variables():
+    """Create the data structure available to the Jinja2 renderer when
+    filling in the templates.
+
+    This function extracts all of classes in ``simtk.openmm.openmm`` and returns
+    a dictionary with them grouped into three lists, the integrators, the forces,
+    and the remainder (library_extras).
+
+    A couple core classes are skipped, because they're included manually in the
+    template.
+    """
+    data = {
+        'integrators': [],
+        'forces': [],
+        'library_extras': [],
+        'units': [],
+    }
+
+    mm_klasses = inspect.getmembers(simtk.openmm, predicate=inspect.isclass)
+
+
+    # gather all Force subclasses
+    for name, klass in mm_klasses:
+        if issubclass(klass, simtk.openmm.openmm.Force):
+            data['forces'].append(fullname(klass))
+
+    # gather all Integrator subclasses
+    for _, klass in mm_klasses:
+        if issubclass(klass, simtk.openmm.openmm.Integrator):
+            data['integrators'].append(fullname(klass))
+
+    # gather all extra subclasses in simtk.openmm.openmm
+
+    # core classes that are already included in library.rst.jinja2
+    exclude = ['simtk.openmm.openmm.Platform', 'simtk.openmm.openmm.Context',
+              'simtk.openmm.openmm.System', 'simtk.openmm.openmm.State']
+    exclude.extend(data['forces'])
+    exclude.extend(data['integrators'])
+
+    # these classes are useless and not worth documenting.
+    exclude.extend([
+        'simtk.openmm.openmm.SwigPyIterator',
+        'simtk.openmm.openmm.OpenMMException'])
+
+    for _, klass in mm_klasses:
+        full = fullname(klass)
+        if full not in exclude and not klass.__name__[0].islower():
+            data['library_extras'].append(full)
+
+    # gather units related classes
+    unit_klasses = inspect.getmembers(simtk.unit, predicate=inspect.isclass)
+    for name, klass in unit_klasses:
+        data['units'].append(fullname(klass))
+
+    return data
+
+
+def app_template_variables():
+    """Create the data structure available to the Jinja2 renderer when
+    filling in the templates.
+
+    This function extracts all of classes in ``simtk.openmm.app`` and returns
+    a dictionary with them grouped into three lists, the reporters, the
+    classes with the word "File" in the name, and the remainder.
+
+    Four classes are skipped (see exclude), because they're included manually
+    in the template.
+    """
+    data = {
+        'reporters': [],
+        'fileclasses': [],
+        'app_extras': [],
+    }
+    app_klasses = inspect.getmembers(simtk.openmm.app, predicate=inspect.isclass)
+
+    # gather all Reporters
+    for name, klass in app_klasses:
+        if name.endswith('Reporter'):
+            data['reporters'].append(fullname(klass))
+
+    # gather all classes with "File" in the name
+    for name, klass in app_klasses:
+        if 'File' in name or 'CharmmParameterSet' in name:
+            data['fileclasses'].append(fullname(klass))
+
+    # gather all extra subclasses in simtk.openmm.app
+    exclude = ['simtk.openmm.app.topology.Topology',
+               'simtk.openmm.app.topology.Chain',
+               'simtk.openmm.app.topology.Residue',
+               'simtk.openmm.app.topology.Atom',
+               'simtk.openmm.app.modeller.Modeller',
+               'simtk.openmm.app.forcefield.ForceField',
+               'simtk.openmm.app.simulation.Simulation']
+    exclude.extend(data['reporters'])
+    exclude.extend(data['fileclasses'])
+
+    for _, klass in app_klasses:
+        full = fullname(klass)
+        if full not in exclude and not klass.__name__[0].islower():
+            data['app_extras'].append(full)
+
+    return data
+
+
+def main():
+    here = dirname(__file__)
+    templateLoader = jinja2.FileSystemLoader(here)
+    templateEnv = jinja2.Environment(loader=templateLoader)
+    data = library_template_variables()
+    data.update(app_template_variables())
+
+    for template_fn in map(basename, glob(join(here, '*.jinja2'))):
+        output_fn = splitext(template_fn)[0]
+        print('Rendering %s to %s...' % (template_fn, output_fn))
+
+        template = templateEnv.get_template(template_fn)
+        output_text = template.render(data)
+        with open(output_fn, 'w') as f:
+            f.write(output_text)
+
+
+if __name__ == '__main__':
+    main()

docs-source/developerguide/conf.py

@@ -92,7 +92,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'agogo'
+html_theme = 'alabaster'
 
 # 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

docs-source/developerguide/license.rst

-Portions copyright (c) 2011-2015 Stanford University and the Authors
+Portions copyright (c) 2011-2016 Stanford University and the Authors
 
 Contributors: Peter Eastman
 

docs-source/developerguide/make.bat

+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+REM set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\OpenMM.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\OpenMM.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs-source/usersguide/conf.py

@@ -26,7 +26,7 @@ sys.path.append(os.path.abspath('../sphinx'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinxcontrib.bibtex', 'autonumber', 'samepage', 'caption', 'numsec']
+extensions = ['sphinx.ext.mathjax', 'sphinxcontrib.bibtex', 'autonumber', 'samepage', 'caption', 'numsec']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -92,7 +92,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'agogo'
+html_theme = 'alabaster'
 
 # 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

docs-source/usersguide/license.rst

-Portions copyright (c) 2008-2015 Stanford University and the Authors
+Portions copyright (c) 2008-2016 Stanford University and the Authors
 
 Contributors:  Kyle Beauchamp, Christopher Bruns, John Chodera, Peter Eastman, Mark
 Friedrichs, Joy P. Ku, Tom Markland, Vijay Pande, Randy Radmer, Michael Sherman,

docs-source/usersguide/make.bat

+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+REM set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\OpenMM.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\OpenMM.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs-source/usersguide/references.bib

@@ -389,6 +389,17 @@
    type = {Journal Article}
 }
 
+@article{Simmonett2015
+   author = {Simmonett, Andrew C. and Pickard, Frank C. and Shao, Yihan and Cheatham, Thomas E. and Brooks, Bernard R.},
+   title = {Efficient treatment of induced dipoles},
+   journal = {Journal of Chemical Physics},
+   year = {2015},
+   volume = {143},
+   number = {7},
+   pages = {074115},
+   type = {Journal Article}
+}
+
 @article{Sindhikara2009,
   author =   {Sindhikara, Daniel J. and Kim, Seonah and Voter,
                   Arthur F. and Roitberg, Adrian E.},

examples/benchmark.py

@@ -36,22 +36,18 @@ def runOneTest(testName, options):
     if amoeba:
         constraints = None
         epsilon = float(options.epsilon)
-        if epsilon == 0:
-            polarization = 'direct'
-        else:
-            polarization = 'mutual'
         if explicit:
             ff = app.ForceField('amoeba2009.xml')
             pdb = app.PDBFile('5dfr_solv-cube_equil.pdb')
             cutoff = 0.7*unit.nanometers
             vdwCutoff = 0.9*unit.nanometers
-            system = ff.createSystem(pdb.topology, nonbondedMethod=app.PME, nonbondedCutoff=cutoff, vdwCutoff=vdwCutoff, constraints=constraints, ewaldErrorTolerance=0.00075, mutualInducedTargetEpsilon=epsilon, polarization=polarization)
+            system = ff.createSystem(pdb.topology, nonbondedMethod=app.PME, nonbondedCutoff=cutoff, vdwCutoff=vdwCutoff, constraints=constraints, ewaldErrorTolerance=0.00075, mutualInducedTargetEpsilon=epsilon, polarization=options.polarization)
         else:
             ff = app.ForceField('amoeba2009.xml', 'amoeba2009_gk.xml')
             pdb = app.PDBFile('5dfr_minimized.pdb')
             cutoff = 2.0*unit.nanometers
             vdwCutoff = 1.2*unit.nanometers
-            system = ff.createSystem(pdb.topology, nonbondedMethod=app.NoCutoff, constraints=constraints, mutualInducedTargetEpsilon=epsilon, polarization=polarization)
+            system = ff.createSystem(pdb.topology, nonbondedMethod=app.NoCutoff, constraints=constraints, mutualInducedTargetEpsilon=epsilon, polarization=options.polarization)
         for f in system.getForces():
             if isinstance(f, mm.AmoebaMultipoleForce) or isinstance(f, mm.AmoebaVdwForce) or isinstance(f, mm.AmoebaGeneralizedKirkwoodForce) or isinstance(f, mm.AmoebaWcaDispersionForce):
                 f.setForceGroup(1)
@@ -85,18 +81,12 @@ def runOneTest(testName, options):
     print('Step Size: %g fs' % dt.value_in_unit(unit.femtoseconds))
     properties = {}
     initialSteps = 5
-    if options.device is not None:
-        if platform.getName() == 'CUDA':
-            properties['CudaDeviceIndex'] = options.device
-        elif platform.getName() == 'OpenCL':
-            properties['OpenCLDeviceIndex'] = options.device
+    if options.device is not None and platform.getName() in ('CUDA', 'OpenCL'):
+        properties['DeviceIndex'] = options.device
         if ',' in options.device or ' ' in options.device:
             initialSteps = 250
-    if options.precision is not None:
-        if platform.getName() == 'CUDA':
-            properties['CudaPrecision'] = options.precision
-        elif platform.getName() == 'OpenCL':
-            properties['OpenCLPrecision'] = options.precision
+    if options.precision is not None and platform.getName() in ('CUDA', 'OpenCL'):
+        properties['Precision'] = options.precision
     
     # Run the simulation.
     
@@ -127,7 +117,8 @@ parser.add_option('--platform', dest='platform', choices=platformNames, help='na
 parser.add_option('--test', dest='test', choices=('gbsa', 'rf', 'pme', 'amoebagk', 'amoebapme'), help='the test to perform: gbsa, rf, pme, amoebagk, or amoebapme [default: all]')
 parser.add_option('--pme-cutoff', default='0.9', dest='cutoff', type='float', help='direct space cutoff for PME in nm [default: 0.9]')
 parser.add_option('--seconds', default='60', dest='seconds', type='float', help='target simulation length in seconds [default: 60]')
-parser.add_option('--mutual-epsilon', default='1e-4', dest='epsilon', type='float', help='mutual induced epsilon for AMOEBA [default: 1e-4]')
+parser.add_option('--polarization', default='mutual', dest='polarization', choices=('direct', 'extrapolated', 'mutual'), help='the polarization method for AMOEBA: direct, extrapolated, or mutual [default: mutual]')
+parser.add_option('--mutual-epsilon', default='1e-5', dest='epsilon', type='float', help='mutual induced epsilon for AMOEBA [default: 1e-5]')
 parser.add_option('--heavy-hydrogens', action='store_true', default=False, dest='heavy', help='repartition mass to allow a larger time step')
 parser.add_option('--device', default=None, dest='device', help='device index for CUDA or OpenCL')
 parser.add_option('--precision', default='single', dest='precision', choices=('single', 'mixed', 'double'), help='precision mode for CUDA or OpenCL: single, mixed, or double [default: single]')