John's fixes to documentation

docs-source/usersguide/application.rst

 .. include:: header.rst
 
+.. default-domain:: py
+
 .. _the-openmm-application-layer-introduction:
 
 The OpenMM Application Layer: Introduction
@@ -16,7 +18,7 @@ Nearly all molecular simulation applications ask you to write some sort of
 script happens to be written in Python.  But it is no harder to write than those
 for most other applications, and this guide will teach you everything you need
 to know.  There is even a graphical interface that can write the script for you
-based on a simple set of options (see section :ref:`the-script-builder-application`),
+based on a simple set of options (see Section :ref:`the-script-builder-application`),
 so you never need to type a single line of code!
 
 On the other hand, if you don’t mind doing a little programming, this approach
@@ -36,17 +38,20 @@ 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).
 
+.. _installing-on-mac-os-x:
+
 Installing on Mac OS X
 **********************
 
 OpenMM works on Mac OS X 10.7 or later.  GPU acceleration is currently only
 supported on Nvidia GPUs, not on AMD or Intel GPUs.
 
-\ **Important:** A serious bug was introduced in Mac OS X 10.7.5 that prevents
-OpenMM’s OpenCL platform from working correctly.  At the time of this writing,
-the bug is present in all versions from 10.7.5 onward.  The CUDA platform (see
-below) is not affected by the bug, so if you have an affected version of OS X,
-you should use it instead of the OpenCL platform.
+.. warning::
+   A serious bug was introduced in Mac OS X 10.7.5 that prevents
+   OpenMM’s OpenCL platform from working correctly.  At the time of this writing,
+   the bug is present in all versions from 10.7.5 onward.  The CUDA platform (see
+   below) is not affected by the bug, so if you have an affected version of OS X,
+   you should use it instead of the OpenCL platform.
 
 1. Download the pre-compiled binary of OpenMM for Mac OS X, then double click
 the .zip file to expand it.
@@ -94,16 +99,16 @@ want to run OpenMM in another Terminal window, you must type the above command
 in the new window.
 
 If you plan to use the CUDA platform, OpenMM also needs to locate the CUDA
-kernel compiler (nvcc).  By default it looks for it in the location
+kernel compiler (:program:`nvcc`).  By default it looks for it in the location
 :file:`/usr/local/cuda/bin/nvcc`.  If you have installed the CUDA toolkit in a different
-location, you can set OPENMM_CUDA_COMPILER to tell OpenMM where to find it.  For
+location, you can set :envvar:`OPENMM_CUDA_COMPILER` to tell OpenMM where to find it.  For
 example,
 ::
 
     export OPENMM_CUDA_COMPILER=/opt/CUDA/cuda-6.0/bin/nvcc
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, cd to the
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, cd to the
 examples folder and type
 ::
 
@@ -119,6 +124,8 @@ the Energy Saver panel.  There will be a checkbox labeled “Automatic graphics
 switching”, which should be disabled.  Otherwise, trying to run OpenMM may
 produce an error.  You will only see this option if your laptop has two GPUs
 
+.. _installing-on-linux:
+
 Installing on Linux
 *******************
 
@@ -126,7 +133,7 @@ Installing on Linux
 .zip file to expand it.
 
 2. Make sure you have Python 2.6 or higher (earlier versions will not work) and
-a C++ compiler (typically gcc or clang) installed on your computer.  You can
+a C++ compiler (typically :program:`gcc` or :program:`clang`) installed on your computer.  You can
 check what version of Python is installed by typing :code:`python` |--|\ :code:`version`
 into a console window.
 
@@ -140,7 +147,7 @@ into a console window.
 
 4. (Optional) If you plan to use the CPU platform, it is recommended that you
 install FFTW.  It is probably available through your system’s package manager
-such as :code:`yum` or :code:`apt-get`\ .  Alternatively, you can download
+such as :program:`yum` or :program:`apt-get`\ .  Alternatively, you can download
 it from http://www.fftw.org.  When configuring it, be sure to specify single
 precision and multiple threads (the |--|\ :code:`enable-float` and
 |--|\ :code:`enable-threads` options).  OpenMM will still work without FFTW, but the
@@ -173,17 +180,17 @@ want to run OpenMM in another console window, you must type the above command in
 the new window.
 
 If you plan to use the CUDA platform, OpenMM also needs to locate the CUDA
-kernel compiler (nvcc).  By default it looks for it in the location
+kernel compiler (:program:`nvcc`).  By default it looks for it in the location
 :file:`/usr/local/cuda/bin/nvcc`.  If you have installed the CUDA toolkit in a different
-location, you can set OPENMM_CUDA_COMPILER to tell OpenMM where to find it.  For
+location, you can set :envvar:`OPENMM_CUDA_COMPILER` to tell OpenMM where to find it.  For
 example,
 ::
 
     export OPENMM_CUDA_COMPILER=/opt/CUDA/cuda-6.0/bin/nvcc
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, cd to the
-examples folder and type
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, :command:`cd` to the
+:file:`examples` folder and type
 ::
 
     python testInstallation.py
@@ -192,6 +199,7 @@ This script confirms that OpenMM is installed, checks whether GPU acceleration
 is available (via that OpenCL and/or CUDA platforms), and verifies that all
 platforms produce consistent results.
 
+.. _installing-on-windows:
 
 Installing on Windows
 *********************
@@ -234,8 +242,8 @@ PATH environment variable.  You may also need to add the Python executable to
 your PATH.
 
   * To find out if the Python executable is already in your PATH, open a command
-    prompt window by clicking on Start -> Programs -> Accessories -> Command Prompt.
-    (On Windows 7, select Start -> All Programs -> Accessories -> Command Prompt).
+    prompt window by clicking on :menuselection:`Start --> Programs --> Accessories --> Command Prompt`.
+    (On Windows 7, select :menuselection:`Start --> All Programs --> Accessories --> Command Prompt`).
     Type
     ::
 
@@ -252,11 +260,11 @@ your PATH.
     location.  You will need to enter it, along with the location of the OpenMM
     libraries, later in this process.
 
-  * Click on Start -> Control Panel -> System (On Windows 7, select Start ->
-    Control Panel -> System and Security -> System)
-  * Click on the “Advanced” tab or the “Advanced system settings” link
-  * Click “Environment Variables”
-  * Under “System variables,” select the line for “Path” and click “Edit…”
+  * Click on :menuselection:`Start --> Control Panel --> System` (On Windows 7, select :menuselection:`Start -->
+    Control Panel --> System and Security --> System`)
+  * Click on the :menuselection:`Advanced` tab or the :menuselection:`Advanced system settings` link
+  * Click :menuselection:`Environment Variables`
+  * Under :menuselection:`System variables`, select the line for :menuselection:`Path` and click :menuselection:`Edit…`
   * Add :file:`C:\\Program Files\\OpenMM\\lib` and :file:`C:\\Program Files\\OpenMM\\lib\\plugins`
     to the “Variable value”.  If you also need to add Python or FFTW to your
     PATH, enter their directory locations here.  Directory locations need to be
@@ -264,13 +272,13 @@ your PATH.
 
 
     If you installed OpenMM somewhere other than the default location, you must also
-    set OPENMM_PLUGIN_DIR to point to the plugins directory.  If this variable is
+    set :envvar:`OPENMM_PLUGIN_DIR` to point to the plugins directory.  If this variable is
     not set, it will assume plugins are in the default location (:file:`C:\\Program
     Files\\OpenMM\\lib\\plugins` or :file:`C:\\Program Files (x86)\\OpenMM\\lib\\plugins`).
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, open a command
-window, cd to the examples folder, and type
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, open a command
+window, :command:`cd` to the :file:`examples` folder, and type
 ::
 
     python testInstallation.py
@@ -279,7 +287,7 @@ This script confirms that OpenMM is installed, checks whether GPU acceleration
 is available (via that OpenCL and/or CUDA platforms), and verifies that all
 platforms produce consistent results.
 
-
+.. _running-simulations:
 
 Running Simulations
 ###################
@@ -290,9 +298,9 @@ A First Example
 ***************
 
 Let’s begin with our first example of an OpenMM script. It loads a PDB file
-called “input.pdb”, models it using the AMBER99SB force field and TIP3P water
+called :file:`input.pdb` that defines a biomolecular system, parameterizes it using the AMBER99SB force field and TIP3P water
 model, energy minimizes it, simulates it for 10,000 steps with a Langevin
-integrator, and saves a frame to a PDB file called “output.pdb” every 1000 time
+integrator, and saves a snapshot frame to a PDB file called :file:`output.pdb` every 1000 time
 steps.
 
 .. samepage::
@@ -320,10 +328,10 @@ steps.
 
         :autonumber:`Example,PDB example`
 
-You can find this script in the “examples” folder of your OpenMM installation.
-It is called “simulatePdb.py”.  To execute it from a command line, go to your
-terminal/console/command prompt window (see Chapter :ref:`installing-openmm`
-on setting up the window to use OpenMM).  Navigate to the “examples” folder by typing
+You can find this script in the :file:`examples` folder of your OpenMM installation.
+It is called :file:`simulatePdb.py`.  To execute it from a command line, go to your
+terminal/console/command prompt window (see Section :ref:`installing-openmm`
+on setting up the window to use OpenMM).  Navigate to the :file:`examples` folder by typing
 ::
 
     cd <examples_directory>
@@ -338,7 +346,7 @@ Then type
     python simulatePdb.py
 
 You can name your own scripts whatever you want, but their names should end with
-“.py”. Let’s go through the script line by line and see how it works.
+``.py``. Let’s go through the script line by line and see how it works.
 ::
 
     from simtk.openmm.app import *
@@ -353,25 +361,27 @@ start of your scripts.
 
     pdb = PDBFile('input.pdb')
 
-This line loads the PDB file from disk.  (The input.pdb file in the examples
+This line loads the PDB file from disk.  (The :file:`input.pdb` file in the :file:`examples`
 directory contains the villin headpiece in explicit solvent.)  More precisely,
-it creates a PDBFile object, passes the file name input.pdb to it as an
+it creates a :class:`PDBFile` object, passes the file name :file:`input.pdb` to it as an
 argument, and assigns the object to a variable called :code:`pdb`\ .  The
-PDBFile object contains the information that was read from the file: the
+:class:`PDBFile` object contains the information that was read from the file: the
 molecular topology and atom positions.  Your file need not be called
-“input.pdb”.  Feel free to change this line to specify any file you want.  Make
-sure you include the single quotes around the file name.
+:file:`input.pdb`.  Feel free to change this line to specify any file you want,
+though it must contain all of the atoms needed by the force field.
+(More information on how to add missing atoms and residues using OpenMM tools can be found in Chapter :ref:`model-building-and-editing`.)
+Make sure you include the single quotes around the file name.
 ::
 
     forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
 
 This line specifies the force field to use for the simulation.  Force fields are
-defined by XML files.  Chapter :ref:`creating-force-fields` describes how to write these files,
-if you are interested in that sort of thing, but you probably won’t need to.  OpenMM
-includes XML files defining lots of standard force fields (see section :ref:`force-fields`).
-In this case we load two of those files: amber99sb.xml, which contains the
-AMBER99SB force field, and tip3p.xml, which contains the TIP3P water model.  The
-ForceField object is assigned to a variable called :code:`forcefield`\ .
+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`.
+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`\ .
 ::
 
     system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME,
@@ -379,30 +389,38 @@ ForceField object is assigned to a variable called :code:`forcefield`\ .
 
 This line combines the force field with the molecular topology loaded from the
 PDB file to create a complete mathematical description of the system we want to
-simulate.  (More precisely, we invoke the ForceField object’s “createSystem”
-function.  It creates a System object, which we assign to the variable
+simulate.  (More precisely, we invoke the :class:`ForceField` object’s :meth:`.createSystem`
+function.  It creates a :class:`System` object, which we assign to the variable
 :code:`system`\ .)  It specifies some additional options about how to do that:
 use particle mesh Ewald for the long range electrostatic interactions
 (:code:`nonbondedMethod=PME`\ ), use a 1 nm cutoff for the direct space
 interactions (\ :code:`nonbondedCutoff=1*nanometer`\ ), and constrain the length
 of all bonds that involve a hydrogen atom (\ :code:`constraints=HBonds`\ ).
+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`.
 ::
 
     integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
 This line creates the integrator to use for advancing the equations of motion.
-It specifies a LangevinIntegrator, which (surprise!) performs Langevin dynamics,
+It specifies a :class:`LangevinIntegrator`, which performs Langevin dynamics,
 and assigns it to a variable called :code:`integrator`\ .  It also specifies
 the values of three parameters that are specific to Langevin dynamics: the
-simulation temperature (300K), the friction coefficient (1 ps\ :sup:`-1`\ ), and
+simulation temperature (300 K), the friction coefficient (1 ps\ :sup:`-1`\ ), and
 the step size (0.002 ps).
 ::
 
     simulation = Simulation(pdb.topology, system, integrator)
 
 This line combines the molecular topology, system, and integrator to begin a new
-simulation.  It creates a Simulation object and assigns it to a variable called
-\ :code:`simulation`\ .  A Simulation object coordinates all the processes
+simulation.  It creates a :class:`Simulation` object and assigns it to a variable called
+\ :code:`simulation`\ .  A :class:`Simulation` object coordinates all the processes
 involved in running a simulation, such as advancing time and writing output.
 ::
 
@@ -422,9 +440,9 @@ PDB file might produce very large forces.
     simulation.reporters.append(PDBReporter('output.pdb', 1000))
 
 This line creates a “reporter” to generate output during the simulation, and
-adds it to the Simulation object’s list of reporters.  A PDBReporter writes
+adds it to the :class:`Simulation` object’s list of reporters.  A :class:`PDBReporter` writes
 structures to a PDB file.  We specify that the output file should be called
-“output.pdb”, and that a structure should be written every 1000 time steps.
+:file:`output.pdb`, and that a structure should be written every 1000 time steps.
 ::
 
     simulation.reporters.append(StateDataReporter(stdout, 1000, step=True,
@@ -436,14 +454,18 @@ information every 1000 time steps: the current step index, the potential energy
 of the system, and the temperature.  We specify :code:`stdout` (not in
 quotes) as the output file, which means to write the results to the console.  We
 also could have given a file name (in quotes), just as we did for the
-PDBReporter, to write the information to a file.
+:class:`PDBReporter`, to write the information to a file.
 ::
 
     simulation.step(10000)
 
 Finally, we run the simulation, integrating the equations of motion for 10,000
 time steps.  Once it is finished, you can load the PDB file into any program you
-want for analysis and visualization (VMD, PyMol, AmberTools, etc.).
+want for analysis and visualization (VMD_, PyMol_, AmberTools_, etc.).
+
+.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
+.. _PyMol: http://www.pymol.org
+.. _AmberTools: http://ambermd.org
 
 .. _using_amber_files:
 
@@ -452,10 +474,10 @@ Using AMBER Files
 
 OpenMM can build a system in several different ways.  One option, as shown
 above, is to start with a PDB file and then select a force field with which to
-model it.  Alternatively, you can use AmberTools to model your system.  In that
-case, you provide a prmtop file and an inpcrd file.  OpenMM loads the files and
-creates a system from them.  This is shown in the following script.  It can be
-found in OpenMM’s “examples” folder with the name “simulateAmber.py”.
+model it.  Alternatively, you can use AmberTools_ to model your system.  In that
+case, you provide a :class:`prmtop` file and an :class:`inpcrd` file.  OpenMM loads the files and
+creates a :class:`System` from them.  This is illustrated in the following script.  It can be
+found in OpenMM’s :file:`examples` folder with the name :file:`simulateAmber.py`.
 
 .. samepage::
     ::
@@ -494,14 +516,23 @@ create AmberPrmtopFile and AmberInpcrdFile objects and assign them to the
 variables :code:`prmtop` and :code:`inpcrd`\ , respectively.  As before,
 you can change these lines to specify any files you want.  Be sure to include
 the single quotes around the file names.
+
+.. note::
+
+    The :class:`AmberPrmtopFile` reader provided by OpenMM only supports "new-style"
+    :file:`prmtop` files introduced in AMBER 6. The AMBER distribution still contains a number of
+    example files that are in the "old-style" :file:`prmtop` format. These "old-style" files will
+    not run in OpenMM.
+
+Next, the :class:`System` object is created in a different way:
 ::
 
     system = prmtop.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
             constraints=HBonds)
 
-This line creates the system.  In the previous section, we loaded the topology
+In the previous section, we loaded the topology
 from a PDB file and then had the force field create a system based on it.  In
-this case, we don’t need a force field; the prmtop file already contains the
+this case, we don’t need a force field; the :file:`prmtop` file already contains the
 force field parameters, so it can create the system
 directly.
 ::
@@ -509,8 +540,8 @@ directly.
     simulation = Simulation(prmtop.topology, system, integrator)
     simulation.context.setPositions(inpcrd.positions)
 
-Notice that we now get the topology from the prmtop file and the atom positions
-from the inpcrd file.  In the previous section, both of these came from a PDB
+Notice that we now get the topology from the :file:`prmtop` file and the atom positions
+from the :file:`inpcrd` file.  In the previous section, both of these came from a PDB
 file, but AMBER puts the topology and positions in separate files.
 
 .. _using_gromacs_files:
@@ -519,10 +550,10 @@ Using Gromacs Files
 *******************
 
 A third option for creating your system is to use the Gromacs setup tools.  They
-produce a gro file containing the coordinates and a top file containing the
+produce a :file:`gro` file containing the coordinates and a :file:`top` file containing the
 topology.  OpenMM can load these exactly as it did the AMBER files.  This is
-shown in the following script.  It can be found in OpenMM’s “examples” folder
-with the name “simulateGromacs.py”.
+shown in the following script.  It can be found in OpenMM’s :file:`examples` folder
+with the name :file:`simulateGromacs.py`.
 
 .. samepage::
     ::
@@ -551,18 +582,18 @@ with the name “simulateGromacs.py”.
         :autonumber:`Example,Gromacs example`
 
 This script is nearly identical to the previous one, just replacing
-AmberInpcrdFile and AmberPrmtopFile with GromacsGroFile and GromacsTopFile.
-Note that when we create the GromacsTopFile, we specify values for two extra
+:class:`AmberInpcrdFile` and :class:`AmberPrmtopFile` with :class:`GromacsGroFile` and :class:`GromacsTopFile`.
+Note that when we create the :class:`GromacsTopFile`, we specify values for two extra
 options.  First, we specify
 :code:`unitCellDimensions=gro.getUnitCellDimensions()`\ .  Unlike OpenMM and
-AMBER, which store the periodic unit cell dimensions with the topology, Gromacs
-stores them with the coordinates.  To let GromacsTopFile create a Topology
+AMBER, which can store periodic unit cell dimensions with the topology, Gromacs
+only stores them with the coordinates.  To let :class:`GromacsTopFile` create a :class:`Topology`
 object, we therefore need to tell it the unit cell dimensions that were loaded
-from the gro file.  You only need to do this if you are simulating a periodic
+from the :file:`gro` file.  You only need to do this if you are simulating a periodic
 system.  For implicit solvent simulations, it usually can be omitted.
 
 Second, we specify :code:`includeDir='/usr/local/gromacs/share/gromacs/top'`\ .  Unlike AMBER,
-which stores all the force field parameters directly in a prmtop file, Gromacs just stores
+which stores all the force field parameters directly in a :file:`prmtop` file, Gromacs just stores
 references to force field definition files that are installed with the Gromacs
 application.  OpenMM needs to know where to find these files, so the
 :code:`includeDir` parameter specifies the directory containing them.  If you
@@ -578,10 +609,10 @@ The Script Builder Application
 ******************************
 
 One option for writing your own scripts is to start with one of the examples
-given above (the one in section :ref:`a-first-example` if you are starting from a PDB file, section
-:ref:`using_amber_files` if you are starting from AMBER prmtop and inpcrd files, or section
+given above (the one in Section :ref:`a-first-example` if you are starting from a PDB file, section
+:ref:`using_amber_files` if you are starting from AMBER :file:`prmtop` and :file:`inpcrd` files, or section
 :ref:`using_gromacs_files` if you are starting from Gromacs gro and top files), then customize it
-to suit your needs.  Another option is to use the OpenMM Script Builder application.
+to suit your needs.  Another option is to use the `OpenMM Script Builder`_ application.
 
 
 .. figure:: ../images/ScriptBuilder.png
@@ -594,9 +625,11 @@ This is a web application available at https://builder.openmm.org.  It provides
 a graphical interface with simple choices for all the most common simulation
 options, then automatically generates a script based on them.  As you change the
 settings, the script is instantly updated to reflect them.  Once everything is
-set the way you want, click the “Save Script” button to save it to disk, or
+set the way you want, click the :menuselection:`Save Script` button to save it to disk, or
 simply copy and paste it into a text editor.
 
+.. _`OpenMM Script Builder`: https://builder.openmm.org
+
 .. _simulation-parameters:
 
 Simulation Parameters
@@ -607,23 +640,22 @@ Now let’s consider lots of ways you might want to customize your script.
 Platforms
 =========
 
-
-When creating a Simulation, you can optionally tell it what Platform to use.
-OpenMM includes four platforms: Reference, CPU, CUDA, and OpenCL.  For a
+When creating a :class:`Simulation`, you can optionally tell it what :class:`Platform` to use.
+OpenMM includes four platforms: :class:`Reference`, :class:`CPU`, :class:`CUDA`, and :class:`OpenCL`.  For a
 description of the differences between them, see Section :ref:`platforms`.  If you do not
-specify a Platform, it will select one automatically.  Usually its choice will
+specify a :class:`Platform`, it will select one automatically.  Usually its choice will
 be reasonable, but you may want to change it.
 
-The following lines specify to use the CUDA Platform:
+The following lines specify to use the :class:`CUDA` platform:
 ::
 
     platform = Platform.getPlatformByName('CUDA')
     simulation = Simulation(prmtop.topology, system, integrator, platform)
 
-The Platform name should be :code:`OpenCL`\ , :code:`CUDA`\ , :code:`CPU`\, or
-:code:`Reference`\ .
+The platform name should be one of :code:`OpenCL`, :code:`CUDA`, :code:`CPU`, or
+:code:`Reference`.
 
-You also can specify Platform-specific properties that customize how
+You also can specify platform-specific properties that customize how
 calculations should be done.  See Chapter :ref:`platform-specific-properties` for details of the
 properties that each Platform supports.  For example, the following lines specify to parallelize
 work across two different GPUs (CUDA devices 0 and 1), doing all computations in
@@ -659,7 +691,7 @@ File                           Force Field
 :code:`amber99sbildn.xml`      AMBER99SB plus improved side chain torsions\ :cite:`Lindorff-Larsen2010`
 :code:`amber99sbnmr.xml`       AMBER99SB with modifications to fit NMR data\ :cite:`Li2010`
 :code:`amber03.xml`            AMBER03\ :cite:`Duan2003`
-:code:`amber10.xml`            AMBER10
+: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 
                                recommended to use AMOEBA 2013 instead.
 :code:`amoeba2013.xml`         AMOEBA 2013\ :cite:`Shi2013`
@@ -709,7 +741,7 @@ File                       Implicit Solvation Model
 =========================  =================================================================================================
 
 
-For example, to use the GBSA-OBC solvation model with the Amber99SB force field,
+For example, to use the GBSA-OBC solvation model with the AMBER99SB force field,
 you would type:
 ::
 
@@ -726,7 +758,7 @@ produce an error since no water parameters are defined:
 Be aware that some force fields and water models include "extra particles", such
 as lone pairs or Drude particles.  Examples include the CHARMM polarizable force
 field and all of the 4 and 5 site water models.  To use these force fields, you
-must first add the extra particles to the Topology.  See section
+must first add the extra particles to the :class:`Topology`.  See section
 :ref:`adding-or-removing-extra-particles` for details.
 
 AMBER Implicit Solvent
@@ -752,7 +784,7 @@ Value          Meaning
 :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`.
+               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).                                                                                                                                      
 =============  ==================================================================================================================================
@@ -771,7 +803,7 @@ are slightly different from those used elsewhere in OpenMM: when building a
 system from a force field, the solvent dielectric defaults to 78.3.
 
 You also can model the effect of a non-zero salt concentration by specifying the
-Debye screening parameter:
+Debye-Huckel screening parameter\ :cite:`Srinivasan1999`:
 ::
 
     system = prmtop.createSystem(implicitSolvent=OBC2, implicitSolventKappa=1.0/nanometer)
@@ -850,7 +882,7 @@ 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.00001.  The :code:`polarization` setting
+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
@@ -876,7 +908,7 @@ Implicit Solvent and Solute Dielectrics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For implicit solvent simulations using the AMOEBA force field, the
-'amoeba2009_gk.xml' file should be included in the initialization of the force
+:file:`amoeba2013_gk.xml` file should be included in the initialization of the force
 field:
 ::
 
@@ -897,7 +929,7 @@ Constraints
 ===========
 
 
-When creating the system (either from a force field or a prmtop file), you can
+When creating the system (either from a force field or an AMBER :file:`prmtop` file), you can
 optionally tell OpenMM to constrain certain bond lengths and angles.  For
 example,
 ::
@@ -920,7 +952,7 @@ Value             Meaning
 
 The main reason to use constraints is that it allows one to use a larger
 integration time step.  With no constraints, one is typically limited to a time
-step of about 1 fs.  With :code:`HBonds` constraints, this can be increased
+step of about 1 fs for typical biomolecular force fields like AMBER or CHARMM.  With :code:`HBonds` constraints, this can be increased
 to about 2 fs.  With :code:`HAngles`\ , it can be further increased to 3.5 or
 4 fs.
 
@@ -934,11 +966,15 @@ disable this behavior with the :code:`rigidWater` parameter:
 Be aware that flexible water may require you to further reduce the integration
 step size, typically to about 0.5 fs.
 
+.. note::
+
+   The AMOEBA forcefield is intended to be used without constraints.
+
 Heavy Hydrogens
 ===============
 
 
-When creating the system (either from a force field or a prmtop file), you can
+When creating the system (either from a force field or an AMBER :file:`prmtop` file), you can
 optionally tell OpenMM to increase the mass of hydrogen atoms.  For example,
 ::
 
@@ -965,7 +1001,7 @@ In the examples of the previous sections, we used Langevin integration:
 
     integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
-The three parameter values in this line are the simulation temperature (300K),
+The three parameter values in this line are the simulation temperature (300 K),
 the friction coefficient (1 ps\ :sup:`-1`\ ), and the step size (0.002 ps).  You
 are free to change these to whatever values you want.  Be sure to specify units
 on all values.  For example, the step size could be written either as
@@ -991,7 +1027,7 @@ Brownian (diffusive) dynamics can be used by specifying the following:
 
     integrator = BrownianIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
-The parameters are the same as for Langevin dynamics: temperature (300K),
+The parameters are the same as for Langevin dynamics: temperature (300 K),
 friction coefficient (1 ps\ :sup:`-1`\ ), and step size (0.002 ps).
 
 Variable Time Step Langevin Integrator
@@ -1037,8 +1073,7 @@ integrator (as shown in the examples above) is usually the best way to do it.
 OpenMM does provide an alternative, however: you can use a Verlet integrator,
 then add an Andersen thermostat to your system to provide temperature coupling.
 
-To do this, add a single line to the script as shown below.  (The lines in grey
-are just for context.)
+To do this, we can add an :class:`AndersenThermostat` object to the :class:`System` as shown below.
 ::
 
     ...
@@ -1048,7 +1083,7 @@ are just for context.)
     integrator = VerletIntegrator(0.002*picoseconds)
     ...
 
-The two parameters of the Andersen thermostat are the temperature (300K) and
+The two parameters of the Andersen thermostat are the temperature (300 K) and
 collision frequency (1 ps\ :sup:`-1`\ ).
 
 Pressure Coupling
@@ -1069,7 +1104,7 @@ previous section:
     ...
 
 The parameters of the Monte Carlo barostat are the pressure (1 bar) and
-temperature (300K).  The barostat assumes the simulation is being run at
+temperature (300 K).  The barostat assumes the simulation is being run at
 constant temperature, but it does not itself do anything to regulate the
 temperature.
 
@@ -1137,7 +1172,8 @@ Removing Center of Mass Motion
 ==============================
 
 
-By default, OpenMM removes all center of mass motion at every time step so the
+By default, :class:`System` objects created with the OpenMM application tools add
+a :class:`CMMotionRemover` that removes all center of mass motion at every time step so the
 system as a whole does not drift with time.  This is almost always what you
 want.  In rare situations, you may want to allow the system to drift with time.
 You can do this by specifying the :code:`removeCMMotion` parameter when you
@@ -1151,19 +1187,22 @@ Writing Trajectories
 ====================
 
 
-OpenMM can save simulation trajectories to disk in two formats: PDB and DCD.
+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.
 
+.. _PDB: http://www.wwpdb.org/documentation/format33/v3.3.html
+.. _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
 example scripts above:
 ::
 
     simulation.reporters.append(PDBReporter('output.pdb', 1000))
 
-The two parameters of the PDBReporter are the output filename and how often (in
+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 “PDBReporter” with “DCDReporter”.  The parameters represent the
+just replace :class:`PDBReporter` with :class:`DCDReporter`.  The parameters represent the
 same values:
 ::
 
@@ -1175,7 +1214,7 @@ Recording Other Data
 
 In addition to saving a trajectory, you may want to record other information
 over the course of a simulation, such as the potential energy or temperature.
-OpenMM provides a reporter for this purpose also.  Create a StateDataReporter
+OpenMM provides a reporter for this purpose also.  Create a :class:`StateDataReporter`
 and add it to the simulation:
 ::
 
@@ -1205,22 +1244,23 @@ separated by spaces instead of commas:
     simulation.reporters.append(StateDataReporter('data.txt', 1000, progress=True,
             temperature=True, totalSteps=10000, separator=' '))
 
+.. _model-building-and-editing:
 
 Model Building and Editing
 ##########################
 
 Sometimes you have a PDB file that needs some work before you can simulate it.
 Maybe it doesn’t contain hydrogen atoms (which is common for structures
-determined by x-ray crystallography), so you need to add them.  Or perhaps you
+determined by X-ray crystallography), so you need to add them.  Or perhaps you
 want to simulate the system in explicit water, but the PDB file doesn’t contain
 water molecules.  Or maybe it does contain water molecules, but they contain the
 wrong number of interaction sites for the water model you want to use.  OpenMM’s
 Modeller class can fix problems such as these.
 
-To use it, create a Modeller object, providing the initial Topology and atom
+To use it, create a :class:`Modeller` object, providing the initial :class:`Topology` and atom
 positions.  You then can invoke various modelling functions on it.  Each one
-modifies the system in some way, creating a new Topology and list of positions.
-When you are all done, you can retrieve them from the Modeller and use them as
+modifies the system in some way, creating a new :class:`Topology` and list of positions.
+When you are all done, you can retrieve them from the :class:`Modeller` and use them as
 the starting point for your simulation:
 
 .. samepage::
@@ -1243,7 +1283,7 @@ Now let’s consider the particular functions you can call.
 Adding Hydrogens
 ****************
 
-Call the addHydrogens function to add missing hydrogen atoms:
+Call the :meth:`addHydrogens` function to add missing hydrogen atoms:
 ::
 
     modeller.addHydrogens(forcefield)
@@ -1274,7 +1314,7 @@ documentation for the Modeller class.
 Adding Solvent
 **************
 
-Call addSolvent to create a box of solvent (water and ions) around the model:
+Call :meth:`addSolvent` to create a box of solvent (water and ions) around the model:
 ::
 
     modeller.addSolvent(forcefield)
@@ -1284,7 +1324,7 @@ molecule comes closer to any solute atom than the sum of their van der Waals
 radii.  It also determines the charge of the solute, and adds enough positive or
 negative ions to make the system neutral.
 
-When called as shown above, addSolvent expects that periodic box dimensions were
+When called as shown above, :meth:`addSolvent` expects that periodic box dimensions were
 specified in the PDB file, and it uses them as the size for the water box.  If
 your PDB file does not specify a box size, or if you want to use a different
 size, you can specify one:
@@ -1303,14 +1343,14 @@ then creates a cubic box of width (solute size)+2*(padding).  The above line
 guarantees that no part of the solute comes closer than 1 nm to any edge of the
 box.
 
-By default, addSolvent creates TIP3P water molecules, but it also supports other
+By default, :meth:`addSolvent` creates TIP3P water molecules, but it also supports other
 water models:
 ::
 
     modeller.addSolvent(forcefield, model='tip5p')
 
-Allowed values for the :code:`model` option are 'tip3p', 'tip3pfb', 'spce', 
-'tip4pew', 'tip4pfb', and 'tip5p'.  Be sure to include the single quotes 
+Allowed values for the :code:`model` option are ``'tip3p'``, ``'tip3pfb'``, ``'spce'``,
+``'tip4pew'``, ``'tip4pfb'``, and ``'tip5p'``.  Be sure to include the single quotes
 around the value.
 
 Another option is to add extra ion pairs to give a desired total ionic strength.
@@ -1331,9 +1371,9 @@ options.  For example, this creates a potassium chloride solution:
 
     modeller.addSolvent(forcefield, ionicStrength=0.1*molar, positiveIon='K+')
 
-Allowed values for :code:`positiveIon` are 'Cs+', 'K+', 'Li+', 'Na+', and
-'Rb+'.  Allowed values for :code:`negativeIon` are 'Cl-', 'Br-', 'F-', and
-'I-'.  Be sure to include the single quotes around the value.  Also be aware
+Allowed values for :code:`positiveIon` are ``'Cs+'``, ``'K+'``, ``'Li+'``, ``'Na+'``, and
+``'Rb+'``.  Allowed values for :code:`negativeIon` are ``'Cl-'``, ``'Br-'``, ``'F-'``, and
+``'I-'``.  Be sure to include the single quotes around the value.  Also be aware
 some force fields do not include parameters for all of these ion types, so you
 need to use types that are supported by your chosen force field.
 
@@ -1345,7 +1385,7 @@ Adding or Removing Extra Particles
 “Extra particles” are particles that do not represent ordinary atoms.  This
 includes the virtual interaction sites used in many water models, Drude
 particles, etc.  If you are using a force field that involves extra particles,
-you must add them to the Topology.  To do this, call:
+you must add them to the :class:`Topology`.  To do this, call:
 ::
 
     modeller.addExtraParticles(forcefield)
@@ -1370,7 +1410,7 @@ Saving The Results
 ******************
 
 Once you have finished editing your model, you can immediately use the resulting
-Topology and atom positions as the input to a Simulation.  If you plan to
+:class:`Topology` object and atom positions as the input to a :class:`Simulation`.  If you plan to
 simulate it many times, though, it is usually better to save the result to a new
 PDB file, then use that as the input for the simulations.  This avoids the cost
 of repeating the modeling operations at the start of every simulation, and also
@@ -1419,7 +1459,7 @@ In the previous chapter, we looked at some basic scripts for running simulations
 and saw lots of ways to customize them.  If that is all you want to do—run
 straightforward molecular simulations—you already know everything you need to
 know.  Just use the example scripts and customize them in the ways described in
-section :ref:`simulation-parameters`.
+Section :ref:`simulation-parameters`.
 
 OpenMM can do far more than that.  Your script has the full OpenMM API at its
 disposal, along with all the power of the Python language and libraries.  In
@@ -1432,18 +1472,18 @@ your own.
 Starting in this section, we will assume some knowledge of programming, as well
 as familiarity with the OpenMM API.  Consult the OpenMM Users Guide and API
 documentation if you are uncertain about how something works.   You can also use
-the Python “help” command.  For example,
+the Python :code:`help` command.  For example,
 ::
 
     help(Simulation)
 
-will print detailed documentation on the Simulation class.
+will print detailed documentation on the :class:`Simulation` class.
 
 Simulated Annealing
 *******************
 
 Here is a very simple example of how to do simulated annealing.  The following
-lines linearly reduce the temperature from 300K to 0K in 100 increments,
+lines linearly reduce the temperature from 300 K to 0 K in 100 increments,
 executing 1000 time steps at each temperature:
 
 .. samepage::
@@ -1461,7 +1501,7 @@ executing 1000 time steps at each temperature:
         :autonumber:`Example,simulated annealing`
 
 This code needs very little explanation.  The loop is executed 100 times.  Each
-time through, it adjusts the temperature of the LangevinIntegrator and then
+time through, it adjusts the temperature of the :class:`LangevinIntegrator` and then
 calls :code:`step(1000)` to take 1000 time steps.
 
 Applying an External Force to Particles: a Spherical Container
@@ -1472,13 +1512,13 @@ spherical container with radius 2 nm.  We implement the container by applying a
 harmonic potential to every particle:
 
 .. math::
-    \begin{array}{lll}
-    E(r) = & 0          & r\le2\\
-           & 100(r-2)^2 & r>2
-    \end{array}
+    E(r) = \begin{cases}
+           0          & r\le2\\
+           100(r-2)^2 & r>2
+           \end{cases}
 
 where *r* is the distance of the particle from the origin, measured in nm.
-We can easily do this using OpenMM’s CustomExternalForce class.  This class
+We can easily do this using OpenMM’s :class:`CustomExternalForce` class.  This class
 applies a force to some or all of the particles in the system, where the energy
 is an arbitrary function of each particle’s (\ *x*\ , *y*\ , *z*\ )
 coordinates.  Here is the code to do it:
@@ -1500,39 +1540,39 @@ coordinates.  Here is the code to do it:
 
         :autonumber:`Example,spherical container`
 
-The first thing it does is create a CustomExternalForce object and add it to the
-System.  The argument to CustomExternalForce is a mathematical expression
-specifying the energy of each particle.  This can be any function of *x*\ ,
+The first thing it does is create a :class:`CustomExternalForce` object and add it to the
+:class:`System`.  The argument to :class:`CustomExternalForce` is a mathematical expression
+specifying the potential energy of each particle.  This can be any function of *x*\ ,
 *y*\ , and *z* you want.  It also can depend on global or per-particle
 parameters.  A wide variety of restraints, steering forces, shearing forces,
 etc. can be implemented with this method.
 
 Next it must specify which particles to apply the force to.  In this case, we
 want it to affect every particle in the system, so we loop over them and call
-:code:`addParticle()` once for each one.  The two arguments are the index of
+:meth:`addParticle` once for each one.  The two arguments are the index of
 the particle to affect, and the list of per-particle parameter values (an empty
 list in this case).  If we had per-particle parameters, such as to make the
 force stronger for some particles than for others, this is where we would
 specify them.
 
-Notice that we do all of this immediately after creating the System.  That is
+Notice that we do all of this immediately after creating the :class:`System`.  That is
 not an arbitrary choice.
 
 .. warning::
 
-    If you add new forces to a System, you must do so before creating the Simulation.
-    Once you create a Simulation, modifying the System will have no effect on that Simulation.
+    If you add new forces to a :class:`System`, you must do so before creating the :class:`Simulation`.
+    Once you create a :class:`Simulation`, modifying the :class:`System` will have no effect on that :class:`Simulation`.
 
 Extracting and Reporting Forces (and other data)
 ************************************************
 
-OpenMM provides reporters for two output formats: PDB and DCD.  Both of those
+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
 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.
 
-Here is the definition of the ForceReporter class:
+Here is the definition of the :class:`ForceReporter` class:
 
 .. samepage::
     ::
@@ -1564,8 +1604,8 @@ should generate reports.  It opens the output file for writing and records the
 reporting interval.  The destructor closes the file.
 
 We then have two methods that every reporter must implement:
-:code:`describeNextReport()` and :code:`report()`\ .  A Simulation object
-periodically calls :code:`describeNextReport()` on each of its reporters to
+:meth:`describeNextReport()` and :meth:`report()`.  A Simulation object
+periodically calls :meth:`describeNextReport()` on each of its reporters to
 find out when that reporter will next generate a report, and what information
 will be needed to generate it.  The return value should be a five element tuple,
 whose elements are as follows:
@@ -1580,12 +1620,12 @@ whose elements are as follows:
 * Whether the next report will need energies.
 
 
-When the time comes for the next scheduled report, the Simulation calls
-:code:`report()` to generate the report.  The arguments are the Simulation
-object, and a State that is guaranteed to contain all the information that was
-requested by :code:`describeNextReport()`\ .  A State object contains a
+When the time comes for the next scheduled report, the :class:`Simulation` calls
+:meth:`report()` to generate the report.  The arguments are the :class:`Simulation`
+object, and a :class:`State` that is guaranteed to contain all the information that was
+requested by :meth:`describeNextReport()`\ .  A State object contains a
 snapshot of information about the simulation, such as forces or particle
-positions.  We call :code:`getForces()` to retrieve the forces and convert
+positions.  We call :meth:`getForces()` to retrieve the forces and convert
 them to the units we want to output (kJ/mole/nm).  Then we loop over each value
 and write it to the file.  To keep the example simple, we just print the values
 in text format, one line per particle.  In a real program, you might choose a
@@ -1606,8 +1646,8 @@ This example illustrates a different sort of analysis.  Instead of running a
 simulation, assume we have already identified a set of structures we are
 interested in.  These structures are saved in a set of PDB files.  We want to
 loop over all the files in a directory, load them in one at a time, and compute
-the potential energy of each one.  Assume we have already created our System and
-Simulation.  The following lines perform the analysis:
+the potential energy of each one.  Assume we have already created our :class:`System` and
+:class:`Simulation`.  The following lines perform the analysis:
 
 .. samepage::
     ::
@@ -1624,9 +1664,9 @@ Simulation.  The following lines perform the analysis:
         :autonumber:`Example,computing energies`
 
 We use Python’s :code:`listdir()` function to list all the files in the
-directory.  We create a PDBFile object for each one and call
-:code:`setPositions()` on the Context to specify the particle positions loaded
-from the PDB file.  We then compute the energy by calling :code:`getState()`
+directory.  We create a :class:`PDBFile` object for each one and call
+:meth:`setPositions()` on the Context to specify the particle positions loaded
+from the PDB file.  We then compute the energy by calling :meth:`getState()`
 with the option :code:`getEnergy=True`\ , and print it to the console along
 with the name of the file.
 

docs-source/usersguide/library.rst

@@ -2614,6 +2614,9 @@ nanometers.  We could just as easily specify it in different units:
 
 The use of units in OpenMM is discussed in the next section.
 
+
+.. _units-and-dimensional-analysis:
+
 Units and dimensional analysis
 ==============================
 

docs-source/usersguide/references.bib

@@ -378,6 +378,16 @@
    type = {Journal Article}
 }
 
+@article{Srinivasan1999
+   author = {Srinivasan, J and Trevathan, M. W. and Beroza, P. and Case, D. A.},
+   title = {Application of a pairwise generalized {Born} model to proteins and nucleic acids: inclusion of salt effects},
+   journal = {Theor. Chem. Acc.},
+   volume = {101},
+   pages = {426-434},
+   year = {1999},
+   type = {Journal Article}
+}
+
 @article{Thole1981
    author = {Thole, B. T.},
    title = {Molecular polarizabilities calculated with a modified dipole interaction},