Skip to content

GitLab

Commit dca54ec7 authored by Saurabh Belsare's avatar Saurabh Belsare
Browse files

Merged fork with latest original master

parents cace5edf 01f9e415
Hide whitespace changes
Inline Side-by-side
Showing with 1700 additions and 256 deletions
docs-source/api-c++/render.py 0 → 100644
View file @ dca54ec7
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 0 → 100644
View file @ dca54ec7
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 0 → 100644
View file @ dca54ec7
{{ 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 0 → 100644
View file @ dca54ec7
.. _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 0 → 100644
View file @ dca54ec7
# -*- 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 0 → 100644
View file @ dca54ec7
.. 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 0 → 100644
View file @ dca54ec7
.. _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 0 → 100644
View file @ dca54ec7
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 0 → 100644
View file @ dca54ec7
"""
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
View file @ dca54ec7
......@@ -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
View file @ dca54ec7
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 0 → 100644
View file @ dca54ec7
@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/application.rst
View file @ dca54ec7
......@@ -38,20 +38,64 @@ Follow these instructions to install OpenMM. There also is an online
troubleshooting guide that describes common problems and how to fix them
(http://wiki.simtk.org/openmm/FAQApp).
There are two ways to install OpenMM: using the Conda package manager (http://conda.pydata.org),
or with standalone installers. (A third option is to compile it from source, which is
discussed in Chapter :ref:`compiling-openmm-from-source-code`.) Using Conda is
the easier method, and is recommended for most users. It is described first,
and then the following sections describe how to use the standalone installers
for various platforms.
Installing with Conda
*********************
Conda is included as part of the Anaconda Python distribution, which you can
download from http://docs.continuum.io/anaconda/install. This is a Python
distribution specifically designed for scientific applications, with many of the
most popular mathematical and scientific packages preinstalled. Alternatively
you can use Miniconda (available from http://conda.pydata.org/miniconda.html),
which includes only Python itself, plus the Conda package manager. That offers
a much smaller initial download, with the ability to then install only the
packages you want.
1. Begin by installing the most recent 64 bit, Python 3.x version of either
Anaconda or Miniconda.
2. (Optional) If you want to run OpenMM on a GPU, install CUDA and/or OpenCL.
* If you have an Nvidia GPU, download CUDA 7.5 from
https://developer.nvidia.com/cuda-downloads. Be sure to install both the
drivers and toolkit. OpenCL is included with the CUDA drivers.
* If you have an AMD GPU and are using Linux or Windows, download the latest
version of the Catalyst driver from http://support.amd.com. On OS X, OpenCL
is included with the operating system and is supported on OS X 10.10.3 or
later.
3. Open a command line terminal and type the following command
::
conda install -c omnia openmm
4. Verify your installation by typing the following command:
::
python -m simtk.testInstallation
This command confirms that OpenMM is installed, checks whether GPU acceleration
is available (via the OpenCL and/or CUDA platforms), and verifies that all
platforms produce consistent results.
.. _installing-on-mac-os-x:
Installing on Mac OS X
**********************
OpenMM works on Mac OS X 10.7 or later.
.. note::
The OpenCL implementations on all recent versions of Mac OS X contain serious
bugs that make them unsuitable for use with OpenMM. GPU acceleration is
therefore only supported with the CUDA platform. This limits it to only Nvidia
GPUs, not AMD or Intel GPUs.
OpenMM works on Mac OS X 10.7 or later. OpenCL is supported on OS X 10.10.3 or
later.
1. Download the pre-compiled binary of OpenMM for Mac OS X, then double click
1. Download the pre-compiled binary of OpenMM for Mac OS X from
https://simtk.org/project/xml/downloads.xml?group_id=161, then double click
the .zip file to expand it.
2. If you have not already done so, install Apple’s Xcode developer tools from
......@@ -61,7 +105,7 @@ 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.)
3. (Optional) If you have an Nvidia GPU and want to use the CUDA platform,
download CUDA 7.0 from https://developer.nvidia.com/cuda-downloads. Be sure to
download CUDA 7.5 from https://developer.nvidia.com/cuda-downloads. Be sure to
install both the drivers and toolkit.
4. (Optional) If you plan to use the CPU platform, it is recommended that you
......@@ -116,7 +160,8 @@ produce an error. You will only see this option if your laptop has two GPUs
Installing on Linux
*******************
1. Download the pre-compiled binary of OpenMM for Linux, then double click the
1. Download the pre-compiled binary of OpenMM for Linux from
https://simtk.org/project/xml/downloads.xml?group_id=161, then double click the
.zip file to expand it.
2. Make sure you have Python 2.6 or higher (earlier versions will not work) and
......@@ -126,7 +171,7 @@ into a console window.
3. (Optional) If you want to run OpenMM on a GPU, install CUDA and/or OpenCL.
* If you have an Nvidia GPU, download CUDA 7.0 from
* If you have an Nvidia GPU, download CUDA 7.5 from
https://developer.nvidia.com/cuda-downloads. Be sure to install both the
drivers and toolkit. OpenCL is included with the CUDA drivers.
* If you have an AMD GPU, download the latest version of the Catalyst driver
......@@ -180,7 +225,8 @@ platforms produce consistent results.
Installing on Windows
*********************
1. Download the pre-compiled binary of OpenMM for Windows, then double click the
1. Download the pre-compiled binary of OpenMM for Windows from
https://simtk.org/project/xml/downloads.xml?group_id=161, then double click the
.zip file to expand it. Move the files to :file:`C:\\Program Files\\OpenMM`.
2. Make sure you have the 64-bit version of Python 3.3 or 3.4 (other versions will not
......@@ -197,7 +243,7 @@ and ignore it.)
4. (Optional) If you want to run OpenMM on a GPU, install CUDA and/or OpenCL.
* If you have an Nvidia GPU, download CUDA 7.0 from
* If you have an Nvidia GPU, download CUDA 7.5 from
https://developer.nvidia.com/cuda-downloads. Be sure to install both the
drivers and toolkit. OpenCL is included with the CUDA drivers.
* If you have an AMD GPU, download the latest version of the Catalyst driver
......@@ -349,7 +395,7 @@ files in the newer PDBx/mmCIF format: just change :class:`PDBFile` to :class:`PD
This line specifies the force field to use for the simulation. Force fields are
defined by XML files. OpenMM includes XML files defining lots of standard force fields (see Section :ref:`force-fields`).
If you find you need to extend the repertoire of force fields available,
you can find more information on how to create these XML files in Section :ref:`creating-force-fields`.
you can find more information on how to create these XML files in Chapter :ref:`creating-force-fields`.
In this case we load two of those files: :file:`amber99sb.xml`, which contains the
Amber99SB force field, and :file:`tip3p.xml`, which contains the TIP3P water model. The
:class:`ForceField` object is assigned to a variable called :code:`forcefield`\ .
......@@ -371,10 +417,8 @@ Note the way we specified the cutoff distance 1 nm using :code:`1*nanometer`:
This is an example of the powerful units tracking and automatic conversion facility
built into the OpenMM Python API that makes specifying unit-bearing quantities
convenient and less error-prone. We could have equivalently specified
:code:`10*angstrom` instead of :code:`1*nanometer` and achieved the same result,
but had we specified the wrong dimensions, such as :code:`1*(nanometer**2)` or
:code:`1*picoseconds`, OpenMM would have thrown an exception. The units system
will be described in more detail later, in Section :ref:`units-and-dimensional-analysis`.
:code:`10*angstrom` instead of :code:`1*nanometer` and achieved the same result.
The units system will be described in more detail later, in Section :ref:`units-and-dimensional-analysis`.
::
integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
......@@ -702,7 +746,7 @@ double precision:
::
platform = Platform.getPlatformByName('CUDA')
properties = {'CudaDeviceIndex': '0,1', 'CudaPrecision': 'double'}
properties = {'DeviceIndex': '0,1', 'Precision': 'double'}
simulation = Simulation(prmtop.topology, system, integrator, platform, properties)
.. _force-fields:
......@@ -723,7 +767,7 @@ For the main force field, OpenMM provides the following options:
.. tabularcolumns:: |l|L|
============================= ================================================================================
File Force Field
File Force Field
============================= ================================================================================
:code:`amber96.xml` Amber96\ :cite:`Kollman1997`
:code:`amber99sb.xml` Amber99\ :cite:`Wang2000` with modified backbone torsions\ :cite:`Hornak2006`
......@@ -731,7 +775,7 @@ File Force Field
:code:`amber99sbnmr.xml` Amber99SB with modifications to fit NMR data\ :cite:`Li2010`
:code:`amber03.xml` Amber03\ :cite:`Duan2003`
:code:`amber10.xml` Amber10 (documented in the AmberTools_ manual as `ff10`)
:code:`amoeba2009.xml` AMOEBA 2009\ :cite:`Ren2002`. This force field is deprecated. It is
:code:`amoeba2009.xml` AMOEBA 2009\ :cite:`Ren2002`. This force field is deprecated. It is
recommended to use AMOEBA 2013 instead.
:code:`amoeba2013.xml` AMOEBA 2013\ :cite:`Shi2013`
:code:`charmm_polar_2013.xml` CHARMM 2013 polarizable force field\ :cite:`Lopes2013`
......@@ -746,14 +790,14 @@ files:
.. tabularcolumns:: |l|L|
=================== ============================================
File Water Model
File Water Model
=================== ============================================
:code:`tip3p.xml` TIP3P water model\ :cite:`Jorgensen1983`
:code:`tip3pfb.xml` TIP3P-FB water model\ :cite:`Wang2014`
:code:`tip4pew.xml` TIP4P-Ew water model\ :cite:`Horn2004`
:code:`tip4pfb.xml` TIP4P-FB water model\ :cite:`Wang2014`
:code:`tip5p.xml` TIP5P water model\ :cite:`Mahoney2000`
:code:`spce.xml` SPC/E water model\ :cite:`Berendsen1987`
:code:`tip3p.xml` TIP3P water model\ :cite:`Jorgensen1983`
:code:`tip3pfb.xml` TIP3P-FB water model\ :cite:`Wang2014`
:code:`tip4pew.xml` TIP4P-Ew water model\ :cite:`Horn2004`
:code:`tip4pfb.xml` TIP4P-FB water model\ :cite:`Wang2014`
:code:`tip5p.xml` TIP5P water model\ :cite:`Mahoney2000`
:code:`spce.xml` SPC/E water model\ :cite:`Berendsen1987`
:code:`swm4ndp.xml` SWM4-NDP water model\ :cite:`Lamoureux2006`
=================== ============================================
......@@ -769,7 +813,7 @@ the following files:
.. tabularcolumns:: |l|L|
========================= =================================================================================================
File Implicit Solvation Model
File Implicit Solvation Model
========================= =================================================================================================
:code:`amber96_obc.xml` GBSA-OBC solvation model\ :cite:`Onufriev2004` for use with Amber96 force field
:code:`amber99_obc.xml` GBSA-OBC solvation model for use with Amber99 force fields
......@@ -821,15 +865,15 @@ allowed values for :code:`implicitSolvent`\ :
.. tabularcolumns:: |l|L|
============= ==================================================================================================================================
Value Meaning
Value Meaning
============= ==================================================================================================================================
:code:`None` No implicit solvent is used.
:code:`HCT` Hawkins-Cramer-Truhlar GBSA model\ :cite:`Hawkins1995` (corresponds to igb=1 in AMBER)
:code:`OBC1` Onufriev-Bashford-Case GBSA model\ :cite:`Onufriev2004` using the GB\ :sup:`OBC`\ I parameters (corresponds to igb=2 in AMBER).
:code:`None` No implicit solvent is used.
:code:`HCT` Hawkins-Cramer-Truhlar GBSA model\ :cite:`Hawkins1995` (corresponds to igb=1 in AMBER)
:code:`OBC1` Onufriev-Bashford-Case GBSA model\ :cite:`Onufriev2004` using the GB\ :sup:`OBC`\ I parameters (corresponds to igb=2 in AMBER).
:code:`OBC2` Onufriev-Bashford-Case GBSA model\ :cite:`Onufriev2004` using the GB\ :sup:`OBC`\ II parameters (corresponds to igb=5 in AMBER).
This is the same model used by the GBSA-OBC files described in Section :ref:`force-fields`.
:code:`GBn` GBn solvation model\ :cite:`Mongan2007` (corresponds to igb=7 in AMBER).
:code:`GBn2` GBn2 solvation model\ :cite:`Nguyen2013` (corresponds to igb=8 in AMBER).
:code:`GBn` GBn solvation model\ :cite:`Mongan2007` (corresponds to igb=7 in AMBER).
:code:`GBn2` GBn2 solvation model\ :cite:`Nguyen2013` (corresponds to igb=8 in AMBER).
============= ==================================================================================================================================
......@@ -867,13 +911,13 @@ The :code:`nonbondedMethod` parameter can have any of the following values:
.. tabularcolumns:: |l|L|
========================= ===========================================================================================================================================================================================================================================
Value Meaning
Value Meaning
========================= ===========================================================================================================================================================================================================================================
:code:`NoCutoff` No cutoff is applied.
:code:`CutoffNonPeriodic` The reaction field method is used to eliminate all interactions beyond a cutoff distance. Not valid for AMOEBA.
:code:`NoCutoff` No cutoff is applied.
:code:`CutoffNonPeriodic` The reaction field method is used to eliminate all interactions beyond a cutoff distance. Not valid for AMOEBA.
:code:`CutoffPeriodic` The reaction field method is used to eliminate all interactions beyond a cutoff distance. Periodic boundary conditions are applied, so each atom interacts only with the nearest periodic copy of every other atom. Not valid for AMOEBA.
:code:`Ewald` Periodic boundary conditions are applied. Ewald summation is used to compute long range interactions. (This option is rarely used, since PME is much faster for all but the smallest systems.) Not valid for AMOEBA.
:code:`PME` Periodic boundary conditions are applied. The Particle Mesh Ewald method is used to compute long range interactions.
:code:`Ewald` Periodic boundary conditions are applied. Ewald summation is used to compute long range interactions. (This option is rarely used, since PME is much faster for all but the smallest systems.) Not valid for AMOEBA.
:code:`PME` Periodic boundary conditions are applied. The Particle Mesh Ewald method is used to compute long range interactions.
========================= ===========================================================================================================================================================================================================================================
......@@ -922,29 +966,33 @@ If :code:`vdwCutoff` is not specified, then the value of
Specifying the Polarization Method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OpenMM allows the setting of several other parameters particular to the AMOEBA
force field. The :code:`mutualInducedTargetEpsilon` option allows you to
specify the accuracy to which the induced dipoles are calculated at each time
step; the default value is 0.01. The :code:`polarization` setting
determines whether the calculation of the induced dipoles is continued until the
dipoles are self-consistent to within the tolerance specified by
:code:`mutualInducedTargetEpsilon` or whether a quick estimate of the induced
dipoles is used instead. The first option corresponds to the
:code:`polarization='mutual'` setting and is the default; the quick estimate
option is given by :code:`polarization='direct'` and in this case,
:code:`mutualInducedTargetEpsilon` is ignored, if provided. Simulations using
:code:`polarization='direct'` will be significantly faster than those with
:code:`polarization='mutual'`\ , but less accurate. Examples using the two
options are given below:
When using the AMOEBA force field, OpenMM allows the induced dipoles to be
calculated in any of three different ways. The slowest but potentially most
accurate method is to iterate the calculation until the dipoles converge to a
specified tolerance. To select this, specify :code:`polarization='mutual'`.
Use the :code:`mutualInducedTargetEpsilon` option to select the tolerance; for
most situations, a value of 0.00001 works well. Alternatively you can specify
:code:`polarization='extrapolated'`. This uses an analytic approximation
:cite:`Simmonett2015` to estimate what the fully converged dipoles will be without
actually continuing the calculation to convergence. In many cases this can be
significantly faster with only a small loss in accuracy. Finally, you can
specify :code:`polarization='direct'` to use the direct polarization
approximation, in which induced dipoles depend only on the fixed multipoles, not
on other induced dipoles. This is even faster, but it produces very different
forces from mutual polarization, so it should only be used with force fields
that have been specifically parameterized for use with this approximation.
Here are examples of using each method:
::
system = forcefield.createSystem(nonbondedMethod=PME,
nonbondedCutoff=1*nanometer,ewaldErrorTolerance=0.00001,
vdwCutoff=1.2*nanometer, mutualInducedTargetEpsilon=0.01)
system = forcefield.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
vdwCutoff=1.2*nanometer, polarization='mutual', mutualInducedTargetEpsilon=0.00001)
system = forcefield.createSystem(nonbondedMethod=PME,
nonbondedCutoff=1*nanometer,ewaldErrorTolerance=0.00001,
vdwCutoff=1.2*nanometer, polarization ='direct')
system = forcefield.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
vdwCutoff=1.2*nanometer, polarization='extrapolated')
system = forcefield.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
vdwCutoff=1.2*nanometer, polarization='direct')
Implicit Solvent and Solute Dielectrics
......@@ -984,11 +1032,11 @@ The :code:`constraints` parameter can have any of the following values:
.. tabularcolumns:: |l|L|
================ =============================================================================================================================================
Value Meaning
Value Meaning
================ =============================================================================================================================================
:code:`None` No constraints are applied. This is the default value.
:code:`HBonds` The lengths of all bonds that involve a hydrogen atom are constrained.
:code:`AllBonds` The lengths of all bonds are constrained.
:code:`None` No constraints are applied. This is the default value.
:code:`HBonds` The lengths of all bonds that involve a hydrogen atom are constrained.
:code:`AllBonds` The lengths of all bonds are constrained.
:code:`HAngles` The lengths of all bonds are constrained. In addition, all angles of the form H-X-H or H-O-X (where X is an arbitrary atom) are constrained.
================ =============================================================================================================================================
......@@ -1272,11 +1320,12 @@ Writing Trajectories
====================
OpenMM can save simulation trajectories to disk in two formats: PDB_ and DCD_.
Both of these are widely supported formats, so you should be able to read them
into most analysis and visualization programs.
OpenMM can save simulation trajectories to disk in three formats: PDB_,
`PDBx/mmCIF`_, and DCD_. All of these are widely supported formats, so you
should be able to read them into most analysis and visualization programs.
.. _PDB: http://www.wwpdb.org/documentation/format33/v3.3.html
.. _PDBx/mmCIF: http://mmcif.wwpdb.org
.. _DCD: http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/dcdplugin.html
To save a trajectory, just add a “reporter” to the simulation, as shown in the
......@@ -1286,9 +1335,9 @@ example scripts above:
simulation.reporters.append(PDBReporter('output.pdb', 1000))
The two parameters of the :class:`PDBReporter` are the output filename and how often (in
number of time steps) output structures should be written. To use DCD format,
just replace :class:`PDBReporter` with :class:`DCDReporter`. The parameters represent the
same values:
number of time steps) output structures should be written. To use PDBx/mmCIF or
DCD format, just replace :class:`PDBReporter` with :class:`PDBxReporter` or
:class:`DCDReporter`. The parameters represent the same values:
::
simulation.reporters.append(DCDReporter('output.dcd', 1000))
......@@ -1329,6 +1378,61 @@ separated by spaces instead of commas:
simulation.reporters.append(StateDataReporter('data.txt', 1000, progress=True,
temperature=True, totalSteps=10000, separator=' '))
Saving Simulation Progress and Results
==========================================
There are three built-in ways to save the results of your simulation in OpenMM
(additional methods can be written yourself or imported through other packages
like mdtraj or parmed). If you are simply interested in saving the structure,
you can write it out as a PDB file using :code:`PDBFile.writeFile()`. You can
see an example of this in the modeller section :ref:`saving-the-results`.
If you are hoping to save more information than just positions, you can use
:code:`simulation.saveState()`. This will save the entire state of the
simulation, including positions, velocities, box dimensions and much more in an
XML file. This same file can be loaded back into OpenMM and used to continue
the simulation. Importantly, because this file is a text file, it can be
transfered between different platforms and different versions of OpenMM. A
potential downside to this approach is that state files are often quite large,
and may not fit all use cases. Here's an example of how to use it:
::
simulation.saveState('output.xml')
To load the simulation back in:
::
simulation.loadState('output.xml')
There is a third way to save your simulation, known as a checkpoint file, which
will save the entire simulation as a binary file. It will allow you to exactly
continue a simulation if the need arises (though whether the simulation is
deterministic depends on platform and methods, see
:ref:`platform-specific-properties-determinism`). There are important caveats
to this approach, however. This binary can only be used to restart simulations
on machines with the same hardware and the same OpenMM version as the one that
saved it. Therefore, it should only be used when it's clear that won't be an
issue.
::
simulation.saveCheckpoint('state.chk')
And can be loaded back in like this:
::
simulation.loadCheckpoint('state.chk')
Finally, OpenMM comes with a built-in reporter for saving checkpoints, the
:class:`CheckpointReporter`, which can be helpful in restarting simulations
that failed unexpectedly or due to outside reasons (e.g. server crash). To save
a checkpoint file every 5,000 steps, for example:
::
simulation.reporters.append(CheckpointReporter('checkpnt.chk', 5000))
Note that the checkpoint reporter will overwrite the last checkpoint file.
.. _model-building-and-editing:
Model Building and Editing
......@@ -1504,6 +1608,8 @@ This is useful, for example, if you want to simulate it with implicit solvent.
Be aware, though, that this only removes water molecules, not ions or other
small molecules that might be considered “solvent”.
.. _saving-the-results:
Saving The Results
******************
......@@ -1664,8 +1770,8 @@ not an arbitrary choice.
Extracting and Reporting Forces (and other data)
************************************************
OpenMM provides reporters for two output formats: PDB_ and DCD_. Both of those
formats store only positions, not velocities, forces, or other data. In this
OpenMM provides reporters for three output formats: PDB_, `PDBx/mmCIF`_ and DCD_.
All of those formats store only positions, not velocities, forces, or other data. In this
section, we create a new reporter that outputs forces. This illustrates two
important things: how to write a reporter, and how to query the simulation for
forces or other data.
......@@ -1674,19 +1780,19 @@ Here is the definition of the :class:`ForceReporter` class:
.. samepage::
::
class ForceReporter(object):
def __init__(self, file, reportInterval):
self._out = open(file, 'w')
self._reportInterval = reportInterval
def __del__(self):
self._out.close()
def describeNextReport(self, simulation):
steps = self._reportInterval - simulation.currentStep%self._reportInterval
return (steps, False, False, True, False)
def report(self, simulation, state):
forces = state.getForces().value_in_unit(kilojoules/mole/nanometer)
for f in forces:
......@@ -1755,7 +1861,7 @@ the potential energy of each one. Assume we have already created our :class:`Sy
pdb = PDBFile(os.path.join('structures', file))
simulation.context.setPositions(pdb.positions)
state = simulation.context.getState(getEnergy=True)
print file, state.getPotentialEnergy()
print(file, state.getPotentialEnergy())
.. caption::
......@@ -1957,6 +2063,150 @@ are :code:`wo1`\ , :code:`wo2`\ , :code:`wo3`\ , :code:`wx1`\ , :code:`wx2`\ ,
:code:`wx3`\ , :code:`wy1`\ , :code:`wy2`\ , :code:`wy3`\ , :code:`p1`\ ,
:code:`p2`\ , and :code:`p3`\ .
<Patches>
=========
A "patch" is a set of rules for modifying a residue template (or possibly multiple
templates at once). For example a terminal amino acid is slightly different from
one in the middle of a chain. A force field could of course define multiple
templates for each amino acid (standard, N-terminal, C-terminal, and monomer),
but since the modifications are the same for nearly all amino acids, it is simpler
to include only the "standard" templates, along with a set of patches for
modifying terminal residues.
Here is an example of a patch definition:
.. code-block:: xml
<Patch name="NTER">
<RemoveAtom name="H"/>
<RemoveBond atomName1="N" atomName2="H"/>
<AddAtom name="H1" type="H"/>
<AddAtom name="H2" type="H"/>
<AddAtom name="H3" type="H"/>
<AddBond atomName1="N" atomName2="H1"/>
<AddBond atomName1="N" atomName2="H2"/>
<AddBond atomName1="N" atomName2="H3"/>
<RemoveExternalBond atomName="N"/>
<ChangeAtom name="N" type="N3"/>
</Patch>
There is one :code:`<Patch>` tag for each patch definition. That in turn may
contain any of the following tags:
* An :code:`<AddAtom>` tag indicates that an atom should be added to the
template. It specifies the name of the atom and its atom type.
* A :code:`<ChangeAtom>` tag indicates that the type of an atom already present
in the template should be altered. It specifies the name of the atom and its
new atom type.
* A :code:`<RemoveAtom>` tag indicates that an atom should be removed from the
template. It specifies the name of the atom to remove.
* An :code:`<AddBond>` tag indicates that a bond should be added to the
template. It specifies the names of the two bonded atoms.
* A :code:`<RemoveBond>` tag indicates that a bond already present in the
template should be removed. It specifies the names of the two bonded atoms.
* An :code:`<AddExternalBond>` tag indicates that a new external bond should be
added to the template. It specifies the name of the bonded atom.
* A :code:`<RemoveExternalBond>` tag indicates that an external bond aleady
present in the template should be removed. It specifies the name of the
bonded atom.
In addition to defining the patches, you also must identify which residue
templates each patch can be applied to. This can be done in two ways. The more
common one is to have each template identify the patches that can be applied to
it. This is done with an :code:`<AllowPatch>` tag:
.. code-block:: xml
<Residue name="ALA">
<AllowPatch name="CTER"/>
<AllowPatch name="NTER"/>
...
</Residue>
Alternatively, the patch can indicate which residues it may be applied to. This
is done with an :code:`<ApplyToResidue>` tag:
.. code-block:: xml
<Patch name="NTER">
<ApplyToResidue name="ALA"/>
<ApplyToResidue name="ARG"/>
...
</Patch>
A patch can alter multiple templates at once. This is useful for creating bonds
between molecules, and allows the atom types in one residue to depend on the
identity of the other residue it is bonded to. To create a multi-residue patch,
added a :code:`residues` attribute to the :code:`<Patch>` tag specifying how many
residues that patch covers. Then whenever you refer to an atom, prefix its name
with the index of the residue it belongs to:
.. code-block:: xml
<Patch name="Disulfide" residues="2">
<RemoveAtom name="1:HG"/>
<RemoveAtom name="2:HG"/>
<AddBond atomName1="1:SG" atomName2="2:SG"/>
<ApplyToResidue name="1:CYS"/>
<ApplyToResidue name="2:CYS"/>
</Patch>
In this example, the patch modifies two residues of the same type, but that need
not always be true. Each :code:`<ApplyToResidue>` tag therefore indicates which
one of the residue templates it modifies may be of the specified type. Similarly,
if a residue template includes an :code:`<AcceptPatch>` tag for a multi-residue
patch, it must specify the name of the patch, followed by the index of the residue
within that patch:
.. code-block:: xml
<AllowPatch name="Disulfide:1"/>
Missing residue templates
=========================
.. CAUTION::
These features are experimental, and their API is subject to change.
You can use the :meth:`getUnmatchedResidues()` method to get a list of residues
in the provided :code:`topology` object that do not currently have a matching
residue template defined in the :class:`ForceField`.
::
pdb = PDBFile('input.pdb')
forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
unmatched_residues = forcefield.getUnmatchedResidues(topology)
This is useful for identifying issues with prepared systems, debugging issues
with residue template definitions, or identifying which additional residues need
to be parameterized.
As a convenience for parameterizing new residues, you can also get a list of
residues and empty residue templates using :meth:`generateTemplatesForUnmatchedResidues`
::
pdb = PDBFile('input.pdb')
forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
[templates, residues] = forcefield.generateTemplatesForUnmatchedResidues(topology)
# Se the atom types
for template in templates:
for atom in template.atoms:
atom.type = ... # set the atom types here
# Register the template with the forcefield.
forcefield.registerResidueTemplate(template)
If you find that templates seem to be incorrectly matched, another useful
function :meth:`getMatchingTemplates()` can help you identify which templates
are being matched:
::
pdb = PDBFile('input.pdb')
forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
templates = forcefield.getMatchingTemplates(topology)
for (residue, template) in zip(pdb.topology.residues(), templates):
print("Residue %d %s matched template %s" % (residue.id, residue.name, template.name))
<HarmonicBondForce>
===================
......@@ -2659,6 +2909,9 @@ The ForceField class is designed to be modular and extensible. This means you
can add support for entirely new force types, such as ones implemented with
plugins.
Adding new force types
======================
For every force class, there is a “generator” class that parses the
corresponding XML tag, then creates Force objects and adds them to the System.
ForceField maintains a map of tag names to generator classes. When a ForceField
......@@ -2722,3 +2975,60 @@ parsing it.
Now you can simply create a ForceField object as usual. If an XML file contains
a :code:`<MyForce>` tag, it will be recognized and processed correctly.
Adding residue template generators
==================================
.. CAUTION::
This feature is experimental, and its API is subject to change.
Typically, when :class:`ForceField` encounters a residue it does not have a template for,
it simply raises an :code:`Exception`, since it does not know how to assign atom types for
the unknown residue.
However, :class:`ForceField` has an API for registering *residue template generators* that are
called when a residue without an existing template is encountered. These generators
may create new residue templates that match existing atom types and parameters, or can
even create new atom types and new parameters that are added to :class:`ForceField`. This
functionality can be useful for adding residue template generators that are able to
parameterize small molecules that are not represented in a protein or nucleic acid
forcefield, for example, or for creating new residue templates for post-translationally
modified residues, covalently-bound ligands, or unnatural amino acids or bases.
To register a new residue template generator named :code:`generator`, simply call the
:meth:`registerTemplateGenerator` method on an existing :class:`ForceField` object:
::
forcefield.registerTemplateGenerator(generator)
This :code:`generator` function must conform to the following API:
::
def generator(forcefield, residue):
"""
Parameters
----------
forcefield : simtk.openmm.app.ForceField
The ForceField object to which residue templates and/or parameters are to be added.
residue : simtk.openmm.app.Topology.Residue
The residue topology for which a template is to be generated.
Returns
-------
success : bool
If the generator is able to successfully parameterize the residue, `True` is returned.
If the generator cannot parameterize the residue, it should return `False` and not
modify `forcefield`.
The generator should either register a residue template directly with
`forcefield.registerResidueTemplate(template)` or it should call `forcefield.loadFile(file)`
to load residue definitions from an ffxml file.
It can also use the `ForceField` programmatic API to add additional atom types (via
`forcefield.registerAtomType(parameters)`) or additional parameters.
"""
The :class:`ForceField` object will be modified by the residue template generator as residues without previously
defined templates are encountered. Because these templates are added to the :class:`ForceField` as new residue
types are encountered, subsequent residues will be parameterized using the same residue templates without
calling the :code:`generator` again.
docs-source/usersguide/conf.py
View file @ dca54ec7
......@@ -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
View file @ dca54ec7
......@@ -154,9 +154,9 @@ OpenMM is based on a layered architecture, as shown in the following diagram:
.. figure:: ../images/ArchitectureLayers.jpg
:align: center
:width: 100%
:autonumber:`Figure,OpenMM architecture`: OpenMM architecture
At the highest level is the OpenMM public API. This is the API developers
program against when using OpenMM within their own applications. It is designed
to be simple, easy to understand, and completely platform independent. This is
......@@ -240,7 +240,7 @@ simulation might look like:
HarmonicAngleForce* angles = new HarmonicAngleForce();
system.addForce(angles);
for (int i = 0; i < numAngles; ++i)
angles->addAngle(angle[i].particle1, angle[i].particle2,
angles->addAngle(angle[i].particle1, angle[i].particle2,
angle[i].particle3, angle[i].angle, angle[i].k);
// ...create and initialize other force field terms in the same way
LangevinIntegrator integrator(temperature, friction, stepSize);
......@@ -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
----------------------
......@@ -506,7 +496,7 @@ Mac and Linux
On Mac and Linux machines, type the following two lines:
::
cd build_openmm
ccmake -i <path to OpenMM src directory>
......@@ -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
......@@ -623,7 +615,7 @@ If you are installing to a system area, such as /usr/local/openmm/, you will
need to type:
::
sudo make install
sudo make install
Step 5: Install the Python API
******************************
......@@ -646,7 +638,7 @@ If you are installing into the system Python, such as /usr/bin/python, you will
need to type:
::
sudo make PythonInstall
sudo make PythonInstall
.. _test-your-build:
......@@ -668,7 +660,7 @@ Mac and Linux
Type:
::
make test
You should see a series of test results like this:
......@@ -688,13 +680,70 @@ some tests are stochastic, and therefore are expected to fail a small fraction
of the time. These tests will say so in the error message:
::
./TestReferenceLangevinIntegrator
./TestReferenceLangevinIntegrator
exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129. Expected 9.97741,
found 10.7884 (This test is stochastic and may occasionally fail)
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:
......@@ -734,12 +783,12 @@ HelloArgon and HelloSodiumChloride also serve as examples of how to do these map
sections below describe the HelloArgon, HelloSodiumChloride, and HelloEthane programs in more detail.
=============== ============== ========== ======== ======================================== ===============
Example Solvent Thermostat Boundary Forces & Constraints API
Example Solvent Thermostat Boundary Forces & Constraints API
=============== ============== ========== ======== ======================================== ===============
Argon Vacuum None None Non-bonded\* C++, C, Fortran
Sodium Chloride Implicit water Langevin None Non-bonded\* C++, C, Fortran
Ethane Vacuum None None Non-bonded\*, stretch, bend, torsion C++
Water Box Explicit water Andersen Periodic Non-bonded\*, stretch, bend, constraints C++
Ethane Vacuum None None Non-bonded\*, stretch, bend, torsion C++
Water Box Explicit water Andersen Periodic Non-bonded\*, stretch, bend, constraints C++
=============== ============== ========== ======== ======================================== ===============
\*van der Waals and Coulomb forces
......@@ -774,7 +823,7 @@ debug binaries.
.. figure:: ../images/VisualStudioSetConfiguration.jpg
:align: center
:width: 100%
:autonumber:`Figure,Visual Studio configuration`: Setting "Solution Configuration" to "Release" mode in Visual Studio
......@@ -789,7 +838,7 @@ previously been compiled.
.. figure:: ../images/VisualStudioLaunch.jpg
:align: center
:width: 100%
:autonumber:`Figure,run in Visual Studio`: Run a program in Visual Studio
You should see a series of lines like the following output on your screen:
......@@ -801,9 +850,9 @@ You should see a series of lines like the following output on your screen:
ATOM 2 AR AR 1 5.000 0.000 0.000 1.00 0.00
ATOM 3 AR AR 1 10.000 0.000 0.000 1.00 0.00
ENDMDL
…
MODEL 250
ATOM 1 AR AR 1 0.233 0.000 0.000 1.00 0.00
ATOM 2 AR AR 1 5.068 0.000 0.000 1.00 0.00
......@@ -819,7 +868,7 @@ You should see a series of lines like the following output on your screen:
ATOM 2 AR AR 1 5.097 0.000 0.000 1.00 0.00
ATOM 3 AR AR 1 9.717 0.000 0.000 1.00 0.00
ENDMDL
Determining the platform being used
-----------------------------------
......@@ -880,20 +929,20 @@ Type:::
Then run the program by typing:
::
./HelloArgon
./HelloArgon
You should see a series of lines like the following output on your screen:
::
REMARK Using OpenMM platform Reference
MODEL 1
ATOM 1 AR AR 1 0.000 0.000 0.000 1.00 0.00
ATOM 2 AR AR 1 5.000 0.000 0.000 1.00 0.00
ATOM 3 AR AR 1 10.000 0.000 0.000 1.00 0.00
ENDMDL
...
MODEL 250
ATOM 1 AR AR 1 0.233 0.000 0.000 1.00 0.00
ATOM 2 AR AR 1 5.068 0.000 0.000 1.00 0.00
......@@ -967,7 +1016,7 @@ The OpenMM header file *OpenMM.h* instructs the program to include
everything defined by the OpenMM libraries. Include the header file by adding
the following line at the top of your program: ::
#include "OpenMM.h"
Running a program on GPU platforms
......@@ -1002,7 +1051,7 @@ simulation. The main components of the simulation are within the function
// Create a system with nonbonded forces.
OpenMM::System system;
OpenMM::NonbondedForce* nonbond = new OpenMM::NonbondedForce();
OpenMM::NonbondedForce* nonbond = new OpenMM::NonbondedForce();
system.addForce(nonbond);
We then add the three argon atoms to the system. For this system, all the data
......@@ -1014,7 +1063,7 @@ simulation. The main components of the simulation are within the function
// Create three atoms.
std::vector<OpenMM::Vec3> initPosInNm(3);
for (int a = 0; a < 3; ++a)
for (int a = 0; a < 3; ++a)
{
initPosInNm[a] = OpenMM::Vec3(0.5*a,0,0); // location, nm
......@@ -1113,7 +1162,7 @@ simulation. The main components of the simulation are within the function
if (timeInPs >= 10.)
break;
// Advance state many steps at a time, for efficient use of OpenMM.
integrator.step(10); // (use a lot more than this normally)
......@@ -1128,7 +1177,7 @@ to ensure you do catch the exception.
.. code-block:: c
int main()
int main()
{
try {
simulateArgon();
......@@ -1152,12 +1201,12 @@ converts them to Angstroms (10\ :sup:`-10` m) to be compatible with the PDB
format. Again, we emphasize how important it is to track the units being used!
.. code-block:: c
void writePdbFrame(int frameNum, const OpenMM::State& state)
void writePdbFrame(int frameNum, const OpenMM::State& state)
{
// Reference atomic positions in the OpenMM State.
const std::vector<OpenMM::Vec3>& posInNm = state.getPositions();
// Use PDB MODEL cards to number trajectory frames
printf("MODEL %d\n", frameNum); // start of frame
for (int a = 0; a < (int)posInNm.size(); ++a)
......@@ -1238,7 +1287,7 @@ MD code, and will be used to demonstrate how to integrate OpenMM with an
existing MD program.
.. code-block:: c
// -----------------------------------------------------------------
// MODELING AND SIMULATION PARAMETERS
// -----------------------------------------------------------------
......@@ -1246,25 +1295,25 @@ existing MD program.
static const double FrictionInPerPs = 91.; // collisions per picosecond
static const double SolventDielectric = 80.; // typical for water
static const double SoluteDielectric = 2.; // typical for protein
static const double StepSizeInFs = 2; // integration step size (fs)
static const double ReportIntervalInFs = 50; // how often to issue PDB frame (fs)
static const double SimulationTimeInPs = 100; // total simulation time (ps)
// Decide whether to request energy calculations.
static const bool WantEnergy = true;
// -----------------------------------------------------------------
// ATOM AND FORCE FIELD DATA
// -----------------------------------------------------------------
// This is not part of OpenMM; just a struct we can use to collect atom
// parameters for this example. Normally atom parameters would come from the
// force field's parameterization file. We're going to use data in Angstrom and
// Kilocalorie units and show how to safely convert to OpenMM's internal unit
// This is not part of OpenMM; just a struct we can use to collect atom
// parameters for this example. Normally atom parameters would come from the
// force field's parameterization file. We're going to use data in Angstrom and
// Kilocalorie units and show how to safely convert to OpenMM's internal unit
// system which uses nanometers and kilojoules.
static struct MyAtomInfo {
const char* pdb;
static struct MyAtomInfo {
const char* pdb;
double mass, charge, vdwRadiusInAng, vdwEnergyInKcal,
gbsaRadiusInAng, gbsaScaleFactor;
double initPosInAng[3];
......@@ -1279,7 +1328,7 @@ existing MD program.
{" CL ", 35.45, -1, 2.4700, 0.1000, 1.735, 0.8, 0, 0, 10},
{""} // end of list
};
Interface routines
==================
......@@ -1325,34 +1374,34 @@ to change the build environment.
double frictionInPs,
double solventDielectric,
double soluteDielectric,
double stepSizeInFs,
double stepSizeInFs,
std::string& platformName);
static void myStepWithOpenMM(MyOpenMMData*, int numSteps);
static void myGetOpenMMState(MyOpenMMData*,
bool wantEnergy,
double& time,
double& energy,
double& energy,
MyAtomInfo atoms[]);
static void myTerminateOpenMM(MyOpenMMData*);
// -----------------------------------------------------------------
// MAIN PROGRAM
// -----------------------------------------------------------------
int main() {
const int NumReports = (int)(SimulationTimeInPs*1000 / ReportIntervalInFs + 0.5);
const int NumSilentSteps = (int)(ReportIntervalInFs / StepSizeInFs + 0.5);
// ALWAYS enclose all OpenMM calls with a try/catch block to make sure that
// usage and runtime errors are caught and reported.
try {
double time, energy;
std::string platformName;
// Set up OpenMM data structures; returns OpenMM Platform name.
MyOpenMMData* omm = myInitializeOpenMM(atoms, Temperature, FrictionInPerPs,
SolventDielectric, SoluteDielectric, StepSizeInFs, platformName);
// Run the simulation:
// (1) Write the first line of the PDB file and the initial configuration.
// (2) Run silently entirely within OpenMM between reporting intervals.
......@@ -1360,26 +1409,26 @@ to change the build environment.
printf("REMARK Using OpenMM platform %s\n", platformName.c_str());
myGetOpenMMState(omm, WantEnergy, time, energy, atoms);
myWritePDBFrame(1, time, energy, atoms);
for (int frame=2; frame <= NumReports; ++frame) {
myStepWithOpenMM(omm, NumSilentSteps);
myGetOpenMMState(omm, WantEnergy, time, energy, atoms);
myWritePDBFrame(frame, time, energy, atoms);
}
}
// Clean up OpenMM data structures.
myTerminateOpenMM(omm);
return 0; // Normal return from main.
}
// Catch and report usage and runtime errors detected by OpenMM and fail.
catch(const std::exception& e) {
printf("EXCEPTION: %s\n", e.what());
return 1;
}
}
We will examine the implementation of each of the four interface routines and
the opaque data structure (handle) in the sections below.
......@@ -1461,7 +1510,7 @@ there would be no change in the main program using the handle.
OpenMM::Context* context;
OpenMM::Integrator* integrator;
};
In addition to establishing pointers to the required three OpenMM objects,
:code:`MyOpenMMData` has a constructor :code:`MyOpenMMData()` that sets
the pointers for the three OpenMM objects to zero and a destructor
......@@ -1480,16 +1529,16 @@ OpenCL, Reference) was used.
.. code-block:: c
static MyOpenMMData*
static MyOpenMMData*
myInitializeOpenMM( const MyAtomInfo atoms[],
double temperature,
double frictionInPs,
double solventDielectric,
double soluteDielectric,
double stepSizeInFs,
std::string& platformName)
double stepSizeInFs,
std::string& platformName)
This initialization routine is very similar to the HelloArgon example program,
except that objects are created and put in the handle. For instance, just as in
the HelloArgon program, the first step is to load the OpenMM plug-ins, so that
......@@ -1498,14 +1547,14 @@ a System is created **and** assigned to the handle :code:`omm`\ .
Similarly, forces are added to the System which is already in the handle.
.. code-block:: c
// Load all available OpenMM plugins from their default location.
OpenMM::Platform::loadPluginsFromDirectory
(OpenMM::Platform::getDefaultPluginsDirectory());
// Allocate space to hold OpenMM objects while we're using them.
MyOpenMMData* omm = new MyOpenMMData();
// Create a System and Force objects within the System. Retain a reference
// to each force object so we can fill in the forces. Note: the OpenMM
// System takes ownership of the force objects;don't delete them yourself.
......@@ -1514,12 +1563,12 @@ Similarly, forces are added to the System which is already in the handle.
OpenMM::GBSAOBCForce* gbsa = new OpenMM::GBSAOBCForce();
omm->system->addForce(nonbond);
omm->system->addForce(gbsa);
// Specify dielectrics for GBSA implicit solvation.
gbsa->setSolventDielectric(solventDielectric);
gbsa->setSoluteDielectric(soluteDielectric);
In the next step, atoms are added to the System within the handle, with
information about each atom coming from the data structure that was passed into
the initialization function from the existing MD code. As shown in the
......@@ -1529,7 +1578,7 @@ atoms. For those unfamiliar with the C++ Standard Template Library, the
the given argument to the end of a C++ “vector” container.
.. code-block:: c
// Specify the atoms and their properties:
// (1) System needs to know the masses.
// (2) NonbondedForce needs charges,van der Waals properties(in MD units!).
......@@ -1538,24 +1587,24 @@ the given argument to the end of a C++ “vector” container.
std::vector<Vec3> initialPosInNm;
for (int n=0; *atoms[n].pdb; ++n) {
const MyAtomInfo& atom = atoms[n];
omm->system->addParticle(atom.mass);
nonbond->addParticle(atom.charge,
atom.vdwRadiusInAng * OpenMM::NmPerAngstrom
atom.vdwRadiusInAng * OpenMM::NmPerAngstrom
* OpenMM::SigmaPerVdwRadius,
atom.vdwEnergyInKcal * OpenMM::KJPerKcal);
gbsa->addParticle(atom.charge,
gbsa->addParticle(atom.charge,
atom.gbsaRadiusInAng * OpenMM::NmPerAngstrom,
atom.gbsaScaleFactor);
// Convert the initial position to nm and append to the array.
const Vec3 posInNm(atom.initPosInAng[0] * OpenMM::NmPerAngstrom,
atom.initPosInAng[1] * OpenMM::NmPerAngstrom,
atom.initPosInAng[2] * OpenMM::NmPerAngstrom);
initialPosInNm.push_back(posInNm);
**Units:** Here we emphasize the need to pay special attention to the
units. As mentioned earlier, the existing MD code in this example uses units
......@@ -1575,21 +1624,21 @@ then gets the platform that will be used to run the simulation and returns that,
along with the handle :code:`omm`\ , back to the calling function.
.. code-block:: c
// Choose an Integrator for advancing time, and a Context connecting the
// System with the Integrator for simulation. Let the Context choose the
// best available Platform. Initialize the configuration from the default
// positions we collected above. Initial velocities will be zero but could
// have been set here.
omm->integrator = new OpenMM::LangevinIntegrator(temperature,
frictionInPs,
omm->integrator = new OpenMM::LangevinIntegrator(temperature,
frictionInPs,
stepSizeInFs * OpenMM::PsPerFs);
omm->context = new OpenMM::Context(*omm->system, *omm->integrator);
omm->context->setPositions(initialPosInNm);
platformName = omm->context->getPlatform().getName();
return omm;
myGetOpenMMState
----------------
......@@ -1601,7 +1650,7 @@ use them without modification.
.. code-block:: c
static void
myGetOpenMMState(MyOpenMMData* omm, bool wantEnergy,
myGetOpenMMState(MyOpenMMData* omm, bool wantEnergy,
double& timeInPs, double& energyInKcal, MyAtomInfo atoms[])
Again, this is another interface routine in which you need to be very careful of
......@@ -1617,19 +1666,19 @@ the existing MD code.
infoMask += OpenMM::State::Energy; // for pot. energy (more expensive)
}
// Forces are also available (and cheap).
const OpenMM::State state = omm->context->getState(infoMask);
timeInPs = state.getTime(); // OpenMM time is in ps already
// Copy OpenMM positions into atoms array and change units from nm to Angstroms.
const std::vector<Vec3>& positionsInNm = state.getPositions();
for (int i=0; i < (int)positionsInNm.size(); ++i)
for (int j=0; j < 3; ++j)
atoms[i].posInAng[j] = positionsInNm[i][j] * OpenMM::AngstromsPerNm;
// If energy has been requested, obtain it and convert from kJ to kcal.
energyInKcal = 0;
if (wantEnergy)
if (wantEnergy)
energyInKcal = (state.getPotentialEnergy() + state.getKineticEnergy())
* OpenMM::KcalPerKJ;
......@@ -1641,8 +1690,8 @@ Integrator, and then sets the number of steps for the Integrator to take. It
does not return any values.
.. code-block:: c
static void
static void
myStepWithOpenMM(MyOpenMMData* omm, int numSteps) {
omm->integrator->step(numSteps);
}
......@@ -1654,12 +1703,12 @@ The :code:`myTerminateOpenMM` routine takes the handle and deletes all the
components, e.g., the Context and System, cleaning up the heap space.
.. code-block:: c
static void
static void
myTerminateOpenMM(MyOpenMMData* omm) {
delete omm;
}
HelloEthane Program
*******************
......@@ -1694,7 +1743,7 @@ routine, we also set up the bonds. If constraints are being used, then we tell
the System about the constrainable bonds:
.. code-block:: c
std::vector< std::pair<int,int> > bondPairs;
for (int i=0; bonds[i].type != EndOfList; ++i) {
const int* atom = bonds[i].atoms;
......@@ -1703,7 +1752,7 @@ the System about the constrainable bonds:
if (UseConstraints && bond.canConstrain) {
system.addConstraint(atom[0], atom[1],
bond.nominalLengthInAngstroms * OpenMM::NmPerAngstrom);
}
}
Otherwise, we need to give the HarmonicBondForce the bond stretch parameters.
......@@ -1716,11 +1765,11 @@ of 2 must be introduced when setting the bond stretch parameters in an OpenMM
system using data from an AMBER system.
.. code-block:: c
bondStretch.addBond(atom[0], atom[1], bond.nominalLengthInAngstroms * OpenMM::NmPerAngstrom,
bond.stiffnessInKcalPerAngstrom2 * 2 * OpenMM::KJPerKcal *
OpenMM::AngstromsPerNm * OpenMM::AngstromsPerNm);
**Non-bond exclusions:** Next, we deal with non-bond exclusions. These are
used for pairs of atoms that appear close to one another in the network of bonds
......@@ -1729,9 +1778,9 @@ are reduced in magnitude. First, we create a list of bonds to generate the non-
bond exclusions:
.. code-block:: c
bondPairs.push_back(std::make_pair(atom[0], atom[1]));
OpenMM’s non-bonded force provides a convenient routine for creating the common
exceptions. These are: (1) for atoms connected by one bond (1-2) or connected by
just one additional bond (1-3), Coulomb and van der Waals terms do not apply;
......@@ -1741,28 +1790,28 @@ general, you may introduce additional exceptions, but the standard ones suffice
here and in many other circumstances.
.. code-block:: c
// Exclude 1-2, 1-3 bonded atoms from nonbonded forces, and scale down 1-4 bonded atoms.
nonbond.createExceptionsFromBonds(bondPairs, Coulomb14Scale, LennardJones14Scale);
// Create the 1-2-3 bond angle harmonic terms.
for (int i=0; angles[i].type != EndOfList; ++i) {
const int* atom = angles[i].atoms;
const AngleType& angle = angleType[angles[i].type];
// See note under bond stretch above regarding the factor of 2 here.
bondBend.addAngle(atom[0],atom[1],atom[2],
angle.nominalAngleInDegrees * OpenMM::RadiansPerDegree,
angle.stiffnessInKcalPerRadian2 * 2 *
angle.stiffnessInKcalPerRadian2 * 2 *
OpenMM::KJPerKcal);
}
// Create the 1-2-3-4 bond torsion (dihedral) terms.
for (int i=0; torsions[i].type != EndOfList; ++i) {
const int* atom = torsions[i].atoms;
const TorsionType& torsion = torsionType[torsions[i].type];
bondTorsion.addTorsion(atom[0],atom[1],atom[2],atom[3],
torsion.periodicity,
bondTorsion.addTorsion(atom[0],atom[1],atom[2],atom[3],
torsion.periodicity,
torsion.phaseInDegrees * OpenMM::RadiansPerDegree,
torsion.amplitudeInKcal * OpenMM::KJPerKcal);
}
......@@ -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++:
......@@ -2105,7 +2175,7 @@ OpenMM_DoubleArray
.. code-block:: c
OpenMM_DoubleArray*
OpenMM_DoubleArray*
OpenMM_DoubleArray_create(int size);
void OpenMM_DoubleArray_destroy(OpenMM_DoubleArray*);
int OpenMM_DoubleArray_getSize(const OpenMM_DoubleArray*);
......@@ -2119,7 +2189,7 @@ OpenMM_StringArray
.. code-block:: c
OpenMM_StringArray*
OpenMM_StringArray*
OpenMM_StringArray_create(int size);
void OpenMM_StringArray_destroy(OpenMM_StringArray*);
int OpenMM_StringArray_getSize(const OpenMM_StringArray*);
......@@ -2133,14 +2203,14 @@ OpenMM_Vec3Array
.. code-block:: c
OpenMM_Vec3Array*
OpenMM_Vec3Array*
OpenMM_Vec3Array_create(int size);
void OpenMM_Vec3Array_destroy(OpenMM_Vec3Array*);
int OpenMM_Vec3Array_getSize(const OpenMM_Vec3Array*);
void OpenMM_Vec3Array_resize(OpenMM_Vec3Array*, int size);
void OpenMM_Vec3Array_append(OpenMM_Vec3Array*, const OpenMM_Vec3 vec);
void OpenMM_Vec3Array_set(OpenMM_Vec3Array*, int index, const OpenMM_Vec3 vec);
const OpenMM_Vec3*
const OpenMM_Vec3*
OpenMM_Vec3Array_get(const OpenMM_Vec3Array*, int index);
OpenMM_BondArray
......@@ -2152,14 +2222,14 @@ its functional return.
.. code-block:: c
OpenMM_BondArray*
OpenMM_BondArray*
OpenMM_BondArray_create(int size);
void OpenMM_BondArray_destroy(OpenMM_BondArray*);
int OpenMM_BondArray_getSize(const OpenMM_BondArray*);
void OpenMM_BondArray_resize(OpenMM_BondArray*, int size);
void OpenMM_BondArray_append(OpenMM_BondArray*, int particle1, int particle2);
void OpenMM_BondArray_set(OpenMM_BondArray*, int index, int particle1, int particle2);
void OpenMM_BondArray_get(const OpenMM_BondArray*, int index,
void OpenMM_BondArray_get(const OpenMM_BondArray*, int index,
int* particle1, int* particle2);
OpenMM_ParameterArray
......@@ -2538,7 +2608,7 @@ Note that if you are using the system Python (as opposed to a locally installed
version), you may need to use the :code:`sudo` command when running
:code:`python setup.py install`\ .
::
export OPENMM_INCLUDE_PATH=/usr/local/openmm/include
export OPENMM_LIB_PATH=/usr/local/openmm/lib
python setup.py build
......@@ -2561,7 +2631,7 @@ notable differences:
::
myContext.getState(getEnergy=True, getForce=False, …)
#. Wherever the C++ API uses references to return multiple values from a method,
the Python API returns a tuple. For example, in C++ you would query a
HarmonicBondForce for a bond’s parameters as follows:
......@@ -2570,7 +2640,7 @@ notable differences:
int particle1, particle2;
double length, k;
f.getBondParameters(i, particle1, particle2, length, k);
In Python, the equivalent code is:
::
......@@ -2612,7 +2682,7 @@ Creating and using OpenMM objects is then done exactly as in C++:
Note that when setting the cutoff distance, we explicitly specify that it is in
nanometers. We could just as easily specify it in different units:
::
nb.setCutoffDistance(12*unit.angstrom)
The use of units in OpenMM is discussed in the next section.
......@@ -2741,7 +2811,7 @@ dimension. For example, dividing a distance by a time results in a velocity.
m = 0.36 * kilogram; # mass
F = m * a; # force in kg*m/s**2::
Multiplication or division of two Units results in a composite Unit.
::
......@@ -3115,7 +3185,7 @@ errors for that system. Finally, the median of those values for all test
systems was computed to give the value shown in the table.
==================================== ======================== ==================== =================== =====================
Force OpenCL (single) OpenCL (double) CUDA (single) CUDA (double)
Force OpenCL (single) OpenCL (double) CUDA (single) CUDA (double)
==================================== ======================== ==================== =================== =====================
Total Force 2.53·10\ :sup:`-6` 1.44·10\ :sup:`-7` 2.56·10\ :sup:`-6` 8.78·10\ :sup:`-8`
HarmonicBondForce 2.88·10\ :sup:`-6` 1.57·10\ :sup:`-13` 2.88·10\ :sup:`-6` 1.57·10\ :sup:`-13`
......@@ -3148,7 +3218,7 @@ precision that was used for calculations (see Chapter :ref:`platform-specific-pr
.. figure:: ../images/EnergyDrift.png
:align: center
:autonumber:`Figure,energy drift`: Total energy versus time for simulations run in three different
precision modes.
......@@ -3249,21 +3319,21 @@ All rotation axis types are supported: ‘Z-then-X’, ‘Bisector’, ‘Z-Bise
================================= ================================== ======================================================================================================================================================================================
TINKER Force OpenMM Force Option/Note
TINKER Force OpenMM Force Option/Note
================================= ================================== ======================================================================================================================================================================================
ebond1 (bondterm) AmoebaBondForce bndtyp='HARMONIC' supported, 'MORSE' not implemented
Eangle71 (angleterm) AmoebaAngleForce angtyp='HARMONIC' and 'IN-PLANE' supported; 'LINEAR' and 'FOURIER' not implemented
etors1a (torsionterm) PeriodicTorsionForce All options implemented; smoothing version(etors1b) not supported
etortor1 (tortorterm) AmoebaTorsionTorsionForce All options implemented
eopbend1 (opbendterm) AmoebaOutOfPlaneBendForce opbtyp = 'ALLINGER' implemented; 'W-D-C' not implemented
epitors1 (pitorsterm) AmoebaPiTorsionForce All options implemented
estrbnd1 (strbndterm) AmoebaStretchBendForce All options implemented
ehal1a (vdwterm) AmoebaVdwForce ehal1b(LIGHTS) not supported
empole1a (mpoleterm) AmoebaMultipoleForce poltyp = 'MUTUAL', 'DIRECT' supported
empole1c (mpoleterm) PME AmoebaMultipoleForce poltyp = 'MUTUAL', 'DIRECT' supported; boundary= 'VACUUM' unsupported
ebond1 (bondterm) AmoebaBondForce bndtyp='HARMONIC' supported, 'MORSE' not implemented
Eangle71 (angleterm) AmoebaAngleForce angtyp='HARMONIC' and 'IN-PLANE' supported; 'LINEAR' and 'FOURIER' not implemented
etors1a (torsionterm) PeriodicTorsionForce All options implemented; smoothing version(etors1b) not supported
etortor1 (tortorterm) AmoebaTorsionTorsionForce All options implemented
eopbend1 (opbendterm) AmoebaOutOfPlaneBendForce opbtyp = 'ALLINGER' implemented; 'W-D-C' not implemented
epitors1 (pitorsterm) AmoebaPiTorsionForce All options implemented
estrbnd1 (strbndterm) AmoebaStretchBendForce All options implemented
ehal1a (vdwterm) AmoebaVdwForce ehal1b(LIGHTS) not supported
empole1a (mpoleterm) AmoebaMultipoleForce poltyp = 'MUTUAL', 'DIRECT' supported
empole1c (mpoleterm) PME AmoebaMultipoleForce poltyp = 'MUTUAL', 'DIRECT' supported; boundary= 'VACUUM' unsupported
esolv1 (solvateterm) | AmoebaWcaDispersionForce, Only born-radius=’grycuk’ and solvate=’GK’ supported; unsupported solvate settings:
| AmoebaGeneralizedKirkwoodForce ‘ASP’, ‘SASA’, ‘ONION’, ‘pb’, 'GB-HPMF’, 'Gk-HPMF’; SASA computation is based on ACE approximation
eurey1 (ureyterm) HarmonicBondForce All options implemented
eurey1 (ureyterm) HarmonicBondForce All options implemented
================================= ================================== ======================================================================================================================================================================================
:autonumber:`Table,mapping from TINKER`\ : Mapping between TINKER and OpenMM AMOEBA forces
......@@ -3532,7 +3602,7 @@ term. This yields much closer agreement between OpenMM and TINKER,
demonstrating that the difference comes entirely from that one term.
========================= ========================== ===================
Solvent Model single double
Solvent Model single double
========================= ========================== ===================
Implicit 1.04·10\ :sup:`-2` 1.04·10\ :sup:`-2`
Implicit (no cavity term) 9.23·10\ :sup:`-6` 1.17·10\ :sup:`-6`
......@@ -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
View file @ dca54ec7
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 0 → 100644
View file @ dca54ec7
@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
View file @ dca54ec7
......@@ -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
View file @ dca54ec7
......@@ -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]')
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment