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/library.rst

@@ -347,11 +347,6 @@ The choice of which platform to use for a simulation depends on various factors:
    OpenCL platform running on the CPU.
 #. The CUDA platform can only be used with NVIDIA GPUs.  For using an AMD or
    Intel GPU, use the OpenCL platform.
-#. When running on recent NVIDIA GPUs (Fermi and Kepler generations), the CUDA
-   platform is usually faster and should be used.  On older GPUs, the OpenCL
-   platform is likely to be faster.  Also, some very old GPUs (GeForce 8000 and
-   9000 series) are only supported by the OpenCL platform, not by the CUDA
-   platform.
 #. The AMOEBA force field only works with the CUDA platform, not with the OpenCL
    platform.  It also works with the Reference and CPU platforms, but the performance
    is usually too slow to be useful on those platforms.
@@ -393,14 +388,9 @@ Mac and Linux: clang or gcc
 
 Use clang or gcc on Mac/Linux.  OpenMM should compile correctly with all recent
 versions of these compilers.  We recommend clang since it produces faster code,
-especially when using the CPU platform.
-
-If you do not already have a compiler installed, you will need to download and
-install it.  On Mac OS X, this means downloading the Xcode Tools from the App
-Store. (With Xcode 4.3, you must then launch Xcode, open the Preferences window,
-go to the Downloads tab, and tell it to install the command line tools.  With
-Xcode 4.2 and earlier, the command line tools are automatically installed when
-you install Xcode.)
+especially when using the CPU platform.  If you do not already have a compiler
+installed, you will need to download and install it.  On Mac OS X, this means
+downloading the Xcode Tools from the App Store.
 
 Windows: Visual Studio
 ----------------------
@@ -545,6 +535,8 @@ There are several variables that can be adjusted in the CMake interface:
   and documentation.
 * Set the variable CMAKE_INSTALL_PREFIX to the location where you want to
   install OpenMM.
+* Set the variable PYTHON_EXECUTABLE to the Python interpreter you plan to use
+  OpenMM with.
 
 
 Configure (press “c”) again.  Adjust any variables that cause an
@@ -695,6 +687,63 @@ of the time.  These tests will say so in the error message:
 
 Congratulations! You successfully have built and installed OpenMM from source.
 
+Building the Documentation (Optional)
+*************************************
+
+The documentation that you're currently reading, as well as the developer guide and API
+documentation can be built through CMake by setting the OpenMM option :code:`OPENMM_GENERATE_API_DOCS=ON`.
+
+User Guide and Developer Guide
+==============================
+
+Generating the user guide and developer guide requires the following dependencies
+
+* Sphinx (http://sphinx-doc.org/)
+
+* sphinxcontrib-bibtex (https://pypi.python.org/pypi/sphinxcontrib-bibtex)
+
+These dependencies may not be available in your system package manager, but should
+be installable through Python's ``pip`` package manager. ::
+
+   pip install sphinx sphinxcontrib-bibtex
+
+The developer and user guides can be built either as HTML or a PDFs. Building the
+PDF version will also require a functional LaTeX installation.
+
+To build the HTML version of the documentation, type: ::
+
+  make sphinxhtml
+
+To build the PDF version of the documentation, type: ::
+
+  make sphinxpdf
+
+
+Python and C++ API Documentation
+================================
+
+The following dependencies are required to build the Python and C++ API documentation.
+
+* Sphinx (http://sphinx-doc.org/)
+
+* sphinxcontrib-lunrsearch (https://pypi.python.org/pypi/sphinxcontrib-lunrsearch)
+
+* sphinxcontrib-autodoc_doxygen (https://pypi.python.org/pypi/sphinxcontrib-autodoc_doxygen)
+
+
+These dependencies may not be available in your system package manager, but should
+be installable through Python's ``pip`` package manager. ::
+
+   pip install sphinx sphinxcontrib-lunrsearch sphinxcontrib-autodoc_doxygen
+
+To build the C++ API documentation, type: ::
+
+  make C++ApiDocs
+
+To build the Python API documentation, type: ::
+
+  make PythonApiDocs
+
 
 .. _openmm-tutorials:
 
@@ -1787,7 +1836,7 @@ Context constructor:
 
     Platform& platform = Platform::getPlatformByName("OpenCL");
     map<string, string> properties;
-    properties["OpenCLDeviceIndex"] = "1";
+    properties["DeviceIndex"] = "1";
     Context context(system, integrator, platform, properties);
 
 After a Context is created, you can use the Platform’s \
@@ -1798,7 +1847,7 @@ OpenCL Platform
 
 The OpenCL Platform recognizes the following Platform-specific properties:
 
-* OpenCLPrecision: This selects what numeric precision to use for calculations.
+* Precision: This selects what numeric precision to use for calculations.
   The allowed values are “single”, “mixed”, and “double”.  If it is set to
   “single”, nearly all calculations are done in single precision.  This is the
   fastest option but also the least accurate.  If it is set to “mixed”, forces are
@@ -1806,7 +1855,7 @@ The OpenCL Platform recognizes the following Platform-specific properties:
   gives much better energy conservation with only a slight decrease in speed.
   If it is set to “double”, all calculations are done in double precision.  This
   is the most accurate option, but is usually much slower than the others.
-* OpenCLUseCpuPme: This selects whether to use the CPU-based PME
+* UseCpuPme: This selects whether to use the CPU-based PME
   implementation.  The allowed values are “true” or “false”.  Depending on your
   hardware, this might (or might not) improve performance.  To use this option,
   you must have FFTW (single precision, multithreaded) installed, and your CPU
@@ -1816,19 +1865,19 @@ The OpenCL Platform recognizes the following Platform-specific properties:
   zero-based index of the platform (in the OpenCL sense, not the OpenMM sense) to use,
   in the order they are returned by the OpenCL platform API.  This is useful, for
   example, in selecting whether to use a GPU or CPU based OpenCL implementation.
-* OpenCLDeviceIndex: When multiple OpenCL devices are available on your
+* DeviceIndex: When multiple OpenCL devices are available on your
   computer, this is used to select which one to use.  The value is the zero-based
   index of the device to use, in the order they are returned by the OpenCL device
   API.
 
 
 The OpenCL Platform also supports parallelizing a simulation across multiple
-GPUs.  To do that, set the OpenCLDeviceIndex property to a comma separated list
+GPUs.  To do that, set the DeviceIndex property to a comma separated list
 of values.  For example,
 
 .. code-block:: c
 
-    properties["OpenCLDeviceIndex"] = "0,1";
+    properties["DeviceIndex"] = "0,1";
 
 This tells it to use both devices 0 and 1, splitting the work between them.
 
@@ -1837,7 +1886,7 @@ CUDA Platform
 
 The CUDA Platform recognizes the following Platform-specific properties:
 
-* CudaPrecision: This selects what numeric precision to use for calculations.
+* Precision: This selects what numeric precision to use for calculations.
   The allowed values are “single”, “mixed”, and “double”.  If it is set to
   “single”, nearly all calculations are done in single precision.  This is the
   fastest option but also the least accurate.  If it is set to “mixed”, forces are
@@ -1845,7 +1894,7 @@ The CUDA Platform recognizes the following Platform-specific properties:
   gives much better energy conservation with only a slight decrease in speed.
   If it is set to “double”, all calculations are done in double precision.  This
   is the most accurate option, but is usually much slower than the others.
-* CudaUseCpuPme: This selects whether to use the CPU-based PME implementation.
+* UseCpuPme: This selects whether to use the CPU-based PME implementation.
   The allowed values are “true” or “false”.  Depending on your hardware, this
   might (or might not) improve performance.  To use this option, you must have
   FFTW (single precision, multithreaded) installed, and your CPU must support SSE
@@ -1863,28 +1912,36 @@ The CUDA Platform recognizes the following Platform-specific properties:
     appends \nvcc.exe to it.  That environment variable is set by the CUDA
     installer, so it usually is present.
 
-* CudaTempDirectory: This specifies a directory where temporary files can be
+* TempDirectory: This specifies a directory where temporary files can be
   written while compiling kernels.  OpenMM usually can locate your operating
   system’s temp directory automatically (for example, by looking for the TEMP
   environment variable), so you rarely need to specify this.
-* CudaDeviceIndex: When multiple CUDA devices are available on your computer,
+* DeviceIndex: When multiple CUDA devices are available on your computer,
   this is used to select which one to use.  The value is the zero-based index of
   the device to use, in the order they are returned by the CUDA API.
-* CudaUseBlockingSync: This is used to control how the CUDA runtime
+* UseBlockingSync: This is used to control how the CUDA runtime
   synchronizes between the CPU and GPU.  If this is set to “true” (the default),
   CUDA will allow the calling thread to sleep while the GPU is performing a
   computation, allowing the CPU to do other work.  If it is set to “false”, CUDA
   will spin-lock while the GPU is working.  Setting it to "false" can improve performance slightly,
   but also prevents the CPU from doing anything else while the GPU is working.
-
+* DeterministicForces: In some cases, the CUDA platform may compute forces
+  in ways that are not fully deterministic (typically differing in what order a
+  set of numbers get added together).  This means that if you compute the forces
+  twice for the same particle positions, there may be tiny differences in the
+  results.  In most cases this is not a problem, but certain algorithms depend
+  on forces being exactly reproducible to the last bit.  If you set this
+  property to "true", it will instead do these calculations in a way that
+  produces fully deterministic results, at the cost of a small decrease in
+  performance.
 
 The CUDA Platform also supports parallelizing a simulation across multiple GPUs.
-To do that, set the CudaDeviceIndex property to a comma separated list of
+To do that, set the DeviceIndex property to a comma separated list of
 values.  For example,
 
 .. code-block:: c
 
-    properties["CudaDeviceIndex"] = "0,1";
+    properties["DeviceIndex"] = "0,1";
 
 This tells it to use both devices 0 and 1, splitting the work between them.
 
@@ -1893,7 +1950,7 @@ CPU Platform
 
 The CPU Platform recognizes the following Platform-specific properties:
 
-* CpuThreads: This specifies the number of CPU threads to use.  If you do not
+* Threads: This specifies the number of CPU threads to use.  If you do not
   specify this, OpenMM will select a default number of threads as follows:
 
   * If an environment variable called OPENMM_CPU_THREADS is set, its value is
@@ -1905,6 +1962,19 @@ The CPU Platform recognizes the following Platform-specific properties:
   running something else on the computer at the same time, and you want to
   prevent OpenMM from monopolizing all available cores.
 
+.. _platform-specific-properties-determinism:
+
+Determinism
+***********
+
+Whether a simulation is deterministic will depend on what plaform you run on in
+addition to what settings/methods you use. For instance, as of this writing,
+using PME on the Reference, OpenCL, and double-precision CUDA will result in
+deterministic simulations. Single-precision CUDA and CPU platforms are not
+deterministic in this case. However, none of this behavior is guaranteed in
+future versions. In many cases it will still result in an identical trajectory.
+If determinism is a critical for your needs, you should carefully check to
+ensure that your settings and platform allow for this.
 
 .. _using-openmm-with-software-written-in-languages-other-than-c++:
 
@@ -3642,4 +3712,3 @@ The equations of motion can be integrated with two different methods:
    temperature, while using a much lower temperature for their relative internal
    motion.  In practice, this produces dipole moments very close to those from the
    SCF solution while being much faster to compute.
-

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]')