From 6b355171cb4a4ff6ab167b0343ff3fb0af1fc85e Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Tue, 27 Mar 2018 16:02:26 -0500
Subject: [PATCH 01/13] Update version for 0.0.5 development.

---
 CMakeLists.txt              | 2 +-
 setup.py                    | 3 ++-
 src/gmx/core/CMakeLists.txt | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 8288e71470..1bd06ce860 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -5,7 +5,7 @@ cmake_minimum_required(VERSION 3.4.3)
 #list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 
 # Sets the PROJECT_VERSION variable, as well...
-project(gmxpy VERSION 0.0.4)
+project(gmxpy VERSION 0.0.5)
 
 add_subdirectory(pybind11)
 
diff --git a/setup.py b/setup.py
index ae99dcdbea..6fe2095a10 100644
--- a/setup.py
+++ b/setup.py
@@ -26,7 +26,7 @@
 from setuptools.command.test import test as TestCommand
 
 #import gmx.version
-__version__ = '0.0.4'
+__version__ = '0.0.5'
 
 extra_link_args=[]
 
@@ -264,6 +264,7 @@ def __init__(self, name, sourcedir=''):
 package_dir=os.path.join('src','gmx')
 # For better or worse, it seems pretty common for distutils to freely stomp around in the source directory during builds.
 with open(os.path.join(package_dir, 'version.py'), 'w') as fh:
+    fh.write("# Version file generated by setup.py\n")
     fh.write("__version__ = '{}'".format(__version__))
 
 package_data = {
diff --git a/src/gmx/core/CMakeLists.txt b/src/gmx/core/CMakeLists.txt
index 1c4b030b3d..49ab1956f0 100644
--- a/src/gmx/core/CMakeLists.txt
+++ b/src/gmx/core/CMakeLists.txt
@@ -7,7 +7,7 @@
 # cmake was invoked with `-DCMAKE_PREFIX_PATH=...` pointing to the GROMACS
 # installation directory. We can also check now for a GROMACS_DIR environment
 # variable and provide it with the HINTS option.
-find_package(gmxapi 0.0.4 REQUIRED
+find_package(gmxapi 0.0.5 REQUIRED
              HINTS "$ENV{GROMACS_DIR}"
              )
 

From 75ba21bfa5cc641bd68d231ce5a7a5ba77570b83 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Tue, 27 Mar 2018 16:03:03 -0500
Subject: [PATCH 02/13] Silence a tox warning about the mpiexec executable.

---
 tox.ini | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tox.ini b/tox.ini
index 8fb7dfd6ec..35487b1f7d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -16,6 +16,7 @@ deps =
 passenv =
     gmxapi_DIR
     GROMACS_DIR
+whitelist_externals = /usr/local/bin/mpiexec
 commands =
     python setup.py install --verbose
     mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose

From 59e3509454ad843b0a19aecc66af3f277c238420 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Tue, 27 Mar 2018 16:06:30 -0500
Subject: [PATCH 03/13] Point at the correct gromacs-gmxapi source.

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index 6fe2095a10..0f3519f000 100644
--- a/setup.py
+++ b/setup.py
@@ -208,7 +208,7 @@ def build_extension(self, ext):
         # Linking is a pain because the package is relocated to the site-packages directory. We should really do this
         # in two stages.
         if build_gromacs:
-            gromacs_url = "https://github.com/kassonlab/gromacs-gmxapi/archive/v0.0.4.zip"
+            gromacs_url = "https://github.com/kassonlab/gromacs-gmxapi/archive/master.zip"
             gmxapi_DIR = os.path.join(extdir, 'data/gromacs')
             extra_cmake_args = ['-DCMAKE_INSTALL_PREFIX=' + gmxapi_DIR,
                                 '-DGMX_FFT_LIBRARY=fftpack',

From 0c76a46a02634bc4af33f04fdcbc544ce3f243f1 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <mei2n@virginia.edu>
Date: Tue, 27 Mar 2018 16:34:49 -0500
Subject: [PATCH 04/13] Update .travis.yml

We should probably be testing against this exact branch.

More robust version checking should probably be made available soon,
but this change is needed for PRs against dev_5 to pass tests.
---
 .travis.yml                   | 6 +++---
 README.md                     | 6 +++---
 setup.py                      | 9 ++++++++-
 src/gmx/test/test_workflow.py | 2 +-
 4 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index ad0623e441..c0b2b930ee 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -35,11 +35,11 @@ before_install:
   - apt list --installed
   - test -n $CC  && unset CC
   - test -n $CXX && unset CXX
-  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/dev_0_0_4.zip
-  - unzip dev_0_0_4.zip
+  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/dev_5.zip
+  - unzip dev_5.zip
 
 install:
-  - pushd gromacs-gmxapi-dev_0_0_4
+  - pushd gromacs-gmxapi-dev_5
   - mkdir build
   - pushd build
   - cmake -DCMAKE_INSTALL_PREFIX=$HOME -DGMX_FFT_LIBRARY=fftpack -DGMX_GPU=OFF -DGMX_OPENMP=OFF -DGMX_SIMD=None -DGMX_USE_RDTSCP=OFF -DGMX_MPI=$GMX_MPI -DGMX_THREAD_MPI=$GMX_THREAD_MPI ..
diff --git a/README.md b/README.md
index 123ed85414..831b87354c 100644
--- a/README.md
+++ b/README.md
@@ -187,9 +187,9 @@ If you will be running the testing suite, you also need `virtualenv` and `tox`.
 
 Get a copy of this repository, if you haven't already. For a released version, you can just download a source package.
 
-    (myenv)$ wget https://github.com/kassonlab/gmxapi/archive/v0.0.4.zip
-    (myenv)$ unzip v0_0_4.zip
-    (myenv)$ cd gmxapi-v0_0_4
+    (myenv)$ wget https://github.com/kassonlab/gmxapi/archive/master.zip
+    (myenv)$ unzip master.zip
+    (myenv)$ cd gmxapi-master
 
 For a development branch, you should probably clone the repository. You may not already have `git` installed on your system or you may need to load a module for it on an HPC system, which you will need to do before trying the following.
 
diff --git a/setup.py b/setup.py
index 0f3519f000..24c4faa46a 100644
--- a/setup.py
+++ b/setup.py
@@ -265,7 +265,14 @@ def __init__(self, name, sourcedir=''):
 # For better or worse, it seems pretty common for distutils to freely stomp around in the source directory during builds.
 with open(os.path.join(package_dir, 'version.py'), 'w') as fh:
     fh.write("# Version file generated by setup.py\n")
-    fh.write("__version__ = '{}'".format(__version__))
+    fh.write("__version__ = '{}'\n".format(__version__))
+    major, minor, patch = __version__.split('.')
+    fh.write("major = {}\n".format(major))
+    fh.write("minor = {}\n".format(minor))
+    fh.write("patch = {}\n".format(patch))
+    fh.write("def api_is_at_least(a, b, c):\n")
+    fh.write("    return (major >= a) and (minor >= b) and (patch >= c)\n\n")
+    fh.write("release = False\n")
 
 package_data = {
         'gmx': ['data/topol.tpr'],
diff --git a/src/gmx/test/test_workflow.py b/src/gmx/test/test_workflow.py
index 7cd452b4bf..cdf2774c26 100644
--- a/src/gmx/test/test_workflow.py
+++ b/src/gmx/test/test_workflow.py
@@ -85,7 +85,7 @@ def test_creation(self):
         """Create an empty workspec and check API features."""
         workspec = gmx.workflow.WorkSpec()
         # Release 0.0.4 will mark the finalization of workspec version 0.1.
-        assert gmx.__version__ == "0.0.4"
+        assert gmx.version.api_is_at_least(0,0,5)
         assert workspec.version == "gmxapi_workspec_0_1"
         # \todo better python package version checking.
     def test_methods(self):

From 11e121d32e508fc6d6cf729d390bc8135fd8aac2 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Tue, 27 Mar 2018 19:09:07 -0500
Subject: [PATCH 05/13] Add some notes on incrementing the release version
 info.

---
 RELEASE.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 RELEASE.txt

diff --git a/RELEASE.txt b/RELEASE.txt
new file mode 100644
index 0000000000..015c6edfbf
--- /dev/null
+++ b/RELEASE.txt
@@ -0,0 +1,18 @@
+Future release notes go here...
+
+When a new release is about to be tagged, version and release information needs to be updated in a few places.
+
+Once the required features in gromacs-gmxapi have been merged to its master branch, update the several lines in
+.travis.yml to reference the gromacs-gmxapi release archive instead of master or a development branch.
+
+Similarly, update the `gromacs_url` embedded in setup.py
+
+After merging the gmxapi development branch to master and before tagging the release, 
+update setup.py so that it writes a version.py file with `release = True`.
+
+Once the release is tagged and any last-minute essentials are cherry-picked to the refreshed development branch,
+bump the version in the development branch in CMakeLists.txt _and_ in setup.py. If / when feature branches
+require new libgmxapi features, `find_package(gmxapi...` can be updated in `src/gmx/core/CMakeLists.txt`. While
+we have the package version check set to REQUIRED, this is probably an immediate update. Sometime after 0.1.0,
+though, we hope we can have some backwards compatibility and leave the libgmxapi version more flexible.
+

From 6acae49f8eff2ea9ded145ffba3bffcfe7e88bbc Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Mon, 2 Apr 2018 15:56:53 -0500
Subject: [PATCH 06/13] Allow tagging of update data to allow multi-restraint
 tests.

---
 src/gmx/context.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/gmx/context.py b/src/gmx/context.py
index 1cfaf092f5..23e5926a74 100644
--- a/src/gmx/context.py
+++ b/src/gmx/context.py
@@ -608,16 +608,21 @@ def __enter__(self):
 
         assert not self.rank is None
 
-        self.part = 0
+        self.part = {}
         # Set up a simple ensemble resource
-        def update(send, recv):
+        def update(send, recv, tag=None):
+            assert not tag is None
+            assert str(tag) != ''
+            if not tag in self.part:
+                self.part[tag] = 0
             self._communicator.Allreduce(send, recv)
             buffer = numpy.array(recv, copy=False)
             buffer /= self.size
+            suffix = '_{}.npz'.format(tag)
             # These will end up in the working directory and each ensemble member will have one
-            filename = "rank{}part{:04d}".format(self.rank, self.part)
+            filename = "rank{}part{:04d}{}".format(self.rank, int(self.part[tag]), suffix)
             numpy.savez(filename, recv=recv)
-            self.part += 1
+            self.part[tag] += 1
 
         self.ensemble_update = update
 

From 33336e11e0341d20ed582c17cd6e227a07255943 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Mon, 2 Apr 2018 16:16:47 -0500
Subject: [PATCH 07/13] Build faster on readthedocs.org. Run faster otherwise.

---
 setup.py | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/setup.py b/setup.py
index 24c4faa46a..4265863e23 100644
--- a/setup.py
+++ b/setup.py
@@ -210,10 +210,19 @@ def build_extension(self, ext):
         if build_gromacs:
             gromacs_url = "https://github.com/kassonlab/gromacs-gmxapi/archive/master.zip"
             gmxapi_DIR = os.path.join(extdir, 'data/gromacs')
-            extra_cmake_args = ['-DCMAKE_INSTALL_PREFIX=' + gmxapi_DIR,
-                                '-DGMX_FFT_LIBRARY=fftpack',
-                                '-DGMX_GPU=OFF',
-                                '-DGMX_THREAD_MPI=ON']
+            if build_for_readthedocs:
+                extra_cmake_args = ['-DCMAKE_INSTALL_PREFIX=' + gmxapi_DIR,
+                                    '-DGMX_FFT_LIBRARY=fftpack',
+                                    '-DGMX_GPU=OFF',
+                                    '-DGMX_OPENMP=OFF',
+                                    '-DGMX_SIMD=None',
+                                    '-DGMX_USE_RDTSCP=OFF',
+                                    '-DGMX_MPI=OFF']
+            else:
+                extra_cmake_args = ['-DCMAKE_INSTALL_PREFIX=' + gmxapi_DIR,
+                                    '-DGMX_BUILD_OWN_FFTW=ON',
+                                    '-DGMX_GPU=OFF',
+                                    '-DGMX_THREAD_MPI=ON']
 
             # Warning: make sure not to recursively build the Python module...
             get_gromacs(gromacs_url,

From f9bd91c235598375f6c50922582fee215605a490 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Mon, 2 Apr 2018 16:59:36 -0500
Subject: [PATCH 08/13] update URL for dev builds

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index 4265863e23..d9c3e015d2 100644
--- a/setup.py
+++ b/setup.py
@@ -208,7 +208,7 @@ def build_extension(self, ext):
         # Linking is a pain because the package is relocated to the site-packages directory. We should really do this
         # in two stages.
         if build_gromacs:
-            gromacs_url = "https://github.com/kassonlab/gromacs-gmxapi/archive/master.zip"
+            gromacs_url = "https://github.com/kassonlab/gromacs-gmxapi/archive/dev_5.zip"
             gmxapi_DIR = os.path.join(extdir, 'data/gromacs')
             if build_for_readthedocs:
                 extra_cmake_args = ['-DCMAKE_INSTALL_PREFIX=' + gmxapi_DIR,

From f2ba5d95470c1614c505804293385d93da3c97dc Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Wed, 25 Apr 2018 16:12:51 +0300
Subject: [PATCH 09/13] Work around broken pip 10.0 until we can ditch pip.

In resolving dependencies for the line
`python -m pip install virtualenv pytest cmake numpy mpi4py networkx --user`
a command is produced calling
`/usr/bin/python -m pip install --ignore-installed --no-user` but
`--no-user` is not a valid pip option.
---
 .travis.yml | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index c0b2b930ee..2055ec27c3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -42,15 +42,21 @@ install:
   - pushd gromacs-gmxapi-dev_5
   - mkdir build
   - pushd build
-  - cmake -DCMAKE_INSTALL_PREFIX=$HOME -DGMX_FFT_LIBRARY=fftpack -DGMX_GPU=OFF -DGMX_OPENMP=OFF -DGMX_SIMD=None -DGMX_USE_RDTSCP=OFF -DGMX_MPI=$GMX_MPI -DGMX_THREAD_MPI=$GMX_THREAD_MPI ..
+  - cmake -DCMAKE_INSTALL_PREFIX=$HOME/gromacs -DGMX_FFT_LIBRARY=fftpack -DGMX_GPU=OFF -DGMX_OPENMP=OFF -DGMX_SIMD=None -DGMX_USE_RDTSCP=OFF -DGMX_MPI=$GMX_MPI -DGMX_THREAD_MPI=$GMX_THREAD_MPI ..
   - make -j4 install
   - popd
   - popd
-  - python -m pip install --upgrade pip --user
-  - pip install --upgrade setuptools --user
-  - pip install virtualenv pytest cmake numpy mpi4py networkx --user
+  # pip 10 appears to be broken
+  - python -m pip install --upgrade pip==9 --user
+  - python -m pip install --upgrade setuptools --user
+  - python -m pip install virtualenv --user
+  - python -m pip install pytest --user
+  - python -m pip install cmake --user
+  - python -m pip install numpy --user
+  - python -m pip install mpi4py --user
+  - python -m pip install networkx --user
 
 script:
-  - GROMACS_DIR=$HOME pip install . --verbose --user
+  - GROMACS_DIR=$HOME/gromacs python -m pip install . --verbose --user
   - mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose 
 

From 8551f2c9daa7e8ffe891ffbeaff68e344828b146 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Sat, 28 Apr 2018 20:59:25 +0300
Subject: [PATCH 10/13] Rearrange user docs.

 *  Begin rearranging docs to be more approachable.
 *  Split user doc into parts.
 *  Move "getting started" docs from README to install.rst. Consolidate
    install instructions in install.rst.
 *  Make README more friendly.
---
 README.md                   | 335 ++++---------------------------
 docs/components/plugins.rst |   5 +
 docs/developerguide.rst     |   1 +
 docs/guides.rst             |   9 -
 docs/index.rst              |   5 +-
 docs/install.rst            | 381 ++++++++++++++++++++++++++++++++++++
 docs/reference.rst          |  69 ++++---
 docs/reference/python.rst   |  45 -----
 docs/usage.rst              |  61 ++++++
 docs/userguide.rst          | 111 +----------
 src/gmx/__init__.py         |   4 +-
 11 files changed, 541 insertions(+), 485 deletions(-)
 delete mode 100644 docs/guides.rst
 create mode 100644 docs/install.rst
 delete mode 100644 docs/reference/python.rst
 create mode 100644 docs/usage.rst

diff --git a/README.md b/README.md
index 831b87354c..1635074539 100644
--- a/README.md
+++ b/README.md
@@ -7,309 +7,60 @@ In this repository, a Python package provides the `gmx` module for high-level in
 
 The project is hosted on [GitHub](https://github.com/kassonlab/gmxapi) and includes
 the `gmxapi` repository along with supporting respositories.
-the `gromacs-gmxapi` repository includes a modified version of GROMACS that
+The [`gromacs-gmxapi`](https://github.com/kassonlab/gromacs-gmxapi) repository includes a modified version of GROMACS that
 supports the latest `gmxapi` features not yet available through an official GROMACS distribution.
+A [sample repository](https://github.com/kassonlab/sample_restraint) illustrates
+how to implement a GROMACS plugin that applies restrained-ensemble forces
+to a loosely-coupled ensemble of simulation trajectories.
 
-See the latest gmxapi documentation at [http://gmxapi.readthedocs.io/en/latest/](http://gmxapi.readthedocs.io/en/latest/)
-
-# Installation
-
-A compatible version of GROMACS must either be already installed or may be installed
-as part of package installation.
-Alternatively, the Python module can be installed during a CMake-driven GROMACS installation.
-
-You will need a few packages installed that are hard for gmxpy to install automatically.
-Before proceeding, install / upgrade the Python package for `cmake`. Note that it is not
-sufficient just to have the command-line CMake tools installed.
-
-    python -m pip install --upgrade pip
-    pip install --upgrade setuptools
-    pip install --upgrade cmake
-    
-If you will be running the testing suite, you also need `virtualenv` and `tox`.
-
-    pip install --upgrade tox
-
-## Python setuptools with existing or shared GROMACS installation
-
-Make sure that you have GROMACS installed with the gmxapi library.
-See https://github.com/kassonlab/gromacs-gmxapi
-and load the appropriate gmxrc or note the installation location
-(`/Users/eric/gromacs` in the following example).
-
-Download this repository and indicate to python where to look for a local GROMACS installation.
-Either first source the GMXRC as described in GROMACS documentation or provide a hint on the command line.
-
-    $ git clone https://github.com/kassonlab/gmxapi.git
-    $ cd gmxapi
-
-Then, if you have sourced your gmxrc or exported GROMACS environment variables, you can just
-
-    $ python setup.py install
-
-or
-
-    $ pip install --upgrade .
-    
-Otherwise, you need to tell Python where to find GROMACS with an environment variable.
-Note that in `bash`, there must not be spaces between the variable name and the equals sign (`=`).
-
-    $ gmxapi_DIR=/Users/eric/gromacs python setup.py install
-
-or
-
-    $ gmxapi_DIR=/Users/eric/gromacs pip install --upgrade .
-
-If you have not installed GROMACS already or if `gmxapi_DIR` does not contain directories like
-`bin` and `share` then you will get an error along the lines of the following.
-
-   CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
-      Could not find a package configuration file provided by "gmxapi" with any
-      of the following names:
-
-        gmxapiConfig.cmake
-        gmxapi-config.cmake
-
-      Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
-      "gmxapi_DIR" to a directory containing one of the above files.  If "gmxapi"
-      provides a separate development package or SDK, be sure it has been
-      installed.
-
-If you are not a system administrator you are encouraged to install in a Python virtual environment,
-created with virtualenv or Conda.
-Otherwise, you will need to specify the `--user` flag to install to your home directory.
-
-## Python setuptools (or pip) with private GROMACS installation
-
-Instead of setting gmxapi_DIR, set `BUILDGROMACS=TRUE` at the beginning of the `pip` command line.
-
-# Python virtual environments
-
-In the world of Python, a virtual environment is a Python installation that is self-contained
-and easy to activate or deactivate to allow normal Python use without additional concerns of
-software compatibility.
-
-Several systems of managing virtual environments exist. gmxapi is tested with
-Python 3's built-in virtualenv and the add-on virtualenv package for Python 2.
-
-The following documentation assumes you have installed a compatible version of GROMACS and
-installed it in the directory `/path/to/gromacs`. Replace `/path/to/gromacs` with the actual
-install location below.
-
-## Anaconda
-
-Get and install [Anaconda](https://docs.anaconda.com/anaconda/install/). Alternatively, on an HPC system
-it may already be provided with a `module`s system. For example:
-
-    $ module load gcc
-    $ module load cmake
-    $ module load anaconda3
-    $ module load openmpi
-
-You don't have to follow all of the instructions for setting up your login profile if you don't want to,
-but if you don't, then the `conda` and `activate` commands below will have to be prefixed by your
-conda installation location. E.g. `~/miniconda3/bin/conda info` or `source ~/miniconda3/bin/activate myEnv`
-
-Create a conda virtual environment. Replace `myEnv` below with whatever convenient name you choose.
-
-    $ conda create -n myGmxapiEnv python=3 pip setuptools cmake networkx mpi4py
-
-Activate, or enter the environment.
-
-    $ source activate myGmxapiEnv
-
-Install the GROMACS gmxapi fork.
-
-    $ git clone https://github.com/kassonlab/gromacs-gmxapi.git gromacs
-    $ mkdir build
-    $ cd build
-    $ cmake ../gromacs -DGMX_GPU=OFF -DGMX_THREAD_MPI=ON -DCMAKE_CXX_COMPILER=`which g++` -DCMAKE_C_COMPILER=`which gcc` -DCMAKE_INSTALL_PREFIX=$HOME/gromacs-gmxapi
-    $ make -j12 && make install
-    $ source $HOME/gromacs-gmxapi/bin/GMXRC
-
-Make sure dependencies are up to date.
-
-    $ python -m pip install --upgrade pip
-    $ pip install --upgrade setuptools
-    $ pip install --upgrade scikit-build cmake networkx
-    $ MPICC=`which mpicc` pip install --upgrade mpi4py
-    $ git clone 
-
-Install the Python module.
-
-    $ git clone https://github.com/kassonlab/gmxapi.git gmxapi
-    $ cd gmxapi
-    $ CC=`which gcc` CXX=`which g++` pip install .
-
-Note: we do not yet have a robust suggestion for setting up `tox` for running the test suite in a conda environment.
-If you come up with a recipe, please let us know. Otherwise, don't worry if you are able to install
-the package but can't get weird errors when you try to run the tests with tox. Instead, just use `pytest` or run the tests in a regular
-(non-conda) Python virtualenv or no virtualenv at all.
-
-## virtualenv
-
-For the ensemble simulations features, you will need an MPI installation. On an HPC system, this means you will probably have to use `module load` to load a compatible set of MPI tools and compilers. Check your HPC documentation or try `module avail` to look for an `openmpi`, `mpich`, or `mvapich` module and matching compiler module. This may be as simple as
+The whole thing is driven at the highest level by a simple Python interface.
 
-    $ module load gcc
-    $ module load mpicc
-
-Note that the compilers loaded might not be the first compilers discovered automatically by the build tools we will use below, so you may have to specify compilers on the command line for consistency. It may be necessary to require that GROMACS, gmxapi, and the sample code are built with the same compiler(s).
-
-Create a Python virtual environment.
-If using Python 2, use the `virtualenv` module. If it is initially not found, install it with `python -m pip install virtualenv --user`. Then,
-
-    $ python -m virtualenv $HOME/myvenv
-
-For Python 3, use the `venv` module.
-
-    $ python -m venv $HOME/myvenv
-
-Activate the virtual environment. Your shell prompt will probably be updated with the name of the environment you created to make it more obvious.
-
-    $ source $HOME/myvenv/bin/activate
-    (myvenv)$
-
-Don't do it now, but you can deactivate the environment by running `deactivate`.
-
-Update your environment and install some dependencies.
-
-    (myvenv)$ python -m pip install --upgrade pip
-    (myvenv)$ pip install --upgrade setuptools
-    (myvenv)$ pip install --upgrade scikit-build cmake networkx
-
-For MPI, we use mpi4py. Make sure it is using the same MPI installation that we are building GROMACS against and building with compatible compilers.
-
-    (myenv)$ MPICC=`which mpicc` pip install --upgrade mpi4py
-
-If you will be running the testing suite, you also need `virtualenv` and `tox`.
-
-    (myenv)$ pip install --upgrade tox
-
-Get a copy of this repository, if you haven't already. For a released version, you can just download a source package.
-
-    (myenv)$ wget https://github.com/kassonlab/gmxapi/archive/master.zip
-    (myenv)$ unzip master.zip
-    (myenv)$ cd gmxapi-master
-
-For a development branch, you should probably clone the repository. You may not already have `git` installed on your system or you may need to load a module for it on an HPC system, which you will need to do before trying the following.
-
-    (myenv)$ git clone https://github.com/kassonlab/gmxapi.git
-    (myenv)$ cd gmxapi
-
-For simplicity, let this package build and install a local GROMACS for you by setting the BUILDGROMACS environment variable. To be on the safe side, make sure to give hints to use the compilers you intend.
-For instance, if we loaded a gcc module, help make sure pip doesn't default to the system `/bin/cc` or some such.
-
-    (myenv)$ BUILDGROMACS=TRUE CC=`which gcc` CXX=`which g++` pip install .
-
-This will take a while because it has to download and install GROMACS as well. If you want more visual stimulation, you can add `--verbose` to the end of the pip command line.
-
-## Docker
-
-Todo: Dockerfile and/or images for building, using, developing, or reading docs.
-
-# Testing
-
-Unit tests are performed individually with `pytest` or as a full installation and test
-suite with `tox`.
-
-From the root of the repository:
-
-    $ gmxapi_DIR=/path/to/gromacs tox
-
-For pytest, first install the package as above. Then,
-
-    $ pytest --pyargs gmx -s --verbose
-
-For a more thorough test that includes the parallel workflow features, make sure you have MPI set up and the `mpi4py` Python package.
-
-    mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose
-
-Note: `tox` may get confused when it tries to create virtual environments when run from within
-a virtual environment. If you get errors, try running the tests from the native Python environment
-or a different virtual environment manager (i.e. not conda). And let us know
-if you come up with any tips or tricks!
-
-# Documentation
-
-Documentation for the Python classes and functions in the gmx module can be accessed in the usual ways, using `pydoc`
-from the command line or `help()` in an interactive Python session.
-
-Additional documentation can be browsed on [readthedocs.org](http://gmxapi.readthedocs.io/en/readthedocs/) or built with Sphinx after installation.
-
-To build the user documentation locally, first make sure you have sphinx installed, such as by doing
-a `pip install sphinx` or by using whatever package management system you are familiar with.
-You may also need to install a `sphinx_rtd_theme` package.
-
-Build *and install* the gmx module.
-
-Then decide what directory you want to put the docs in and call `sphinx-build` to build `html` docs
-from the configuration in the `docs` directory of the gmxpy repository.
-
-Assuming you downloaded the repository to `/path/to/gmxapi` and you want to build the docs in `/path/to/docs`,
-do
-
-    sphinx-build -b html /path/to/gmxapi/docs /path/to/docs
-
-or
-
-    python -m sphinx -b html /path/to/gmxapi/docs /path/to/docs
-
-Then open `/path/to/docs/index.html` in a browser.
+See the latest gmxapi documentation at [http://gmxapi.readthedocs.io/en/latest/](http://gmxapi.readthedocs.io/en/latest/)
 
-Note:
+# Running simulations from Python
 
-If you try to run `sphinx-build` from the root directory of the repository, it will get confused
-and not realize that it should use the package you just installed instead of the unbuilt source code.
-Therefore, I recommend the following complete procedure to download, install, and build docs for the
-`gmxapi` package:
+To run a simulation as you would with the `gmx` command-line tool, a gmxapi
+Python script would look simply like the following.
 
-    $ python -m pip install --upgrade pip
-    $ pip install --upgrade setuptools
-    $ pip install --upgrade cmake
-    $ pip install --upgrade sphinx
-    $ pip install --upgrade sphinx_rtd_theme
-    $ git clone https://github.com/kassonlab/gmxapi.git
-    $ cd gmxapi
-    $ gmxapi_DIR=/path/to/gromacs pip install .
-    $ cd docs
-    $ python -m sphinx -b html . ../html
-    $ cd ..
-    $ open html/index.html
+```py
+    import gmx
+    md = gmx.workflow.from_tpr('myTPRfile.tpr')
+    gmx.run(md)
+```
 
-Note that the periods '.' and '..' in the above commands are important and that there
-are no spaces before or after the equals sign ('=') when specifying the GROMACS path.
+With a plugin, such as the sample [ensemble-restraint](https://github.com/kassonlab/sample_restraint), you can
+run a coupled ensemble of simulations that collectively refine a bias potential.
+Assuming `tpr_list` is a Python list of input files defining the ensemble, and
+`params` is a Python dictionary of keyword arguments,
 
-# Troubleshooting
+```py
+    import gmx
+    import myplugin
 
-Two of the easiest problems to run into are incompatible compilers and incompatible Python.
-Try to make sure that you use the same C and C++ compilers for GROMACS, for the Python package,
-and for the sample plugin. These compilers should also correspond to the `mpicc` compiler
-wrapper used to compile `mpi4py`. In order to build the Python package, you will need the
-Python headers or development installation, which might not already be installed on the machine
-you are using. (If not, then you will get an error about missing `Python.h` at some point.)
-If you have multiple Python installations (or modules available on an HPC system), you could
-try one of the other Python installations, or you or a system administrator could install an
-appropriate Python dev package. Alternatively, you might try installing your own Anaconda or
-MiniConda in your home directory.
+    md = gmx.workflow.from_tpr(tpr_list)
+    potential = gmx.workflow.WorkElement(
+        namespace="myplugin",
+        operation="ensemble_restraint",
+        depends=[],
+        params=params)
+    potential.name = "ensemble_restraint_1"
+    md.add_dependency(potential)
+	gmx.run(md)
+```
 
-If an attempted installation fails with CMake errors about missing "gmxapi", make
-sure that Gromacs is installed and can be found during installation. For instance,
+Currently, given an MPI environment, gmxapi would run the above workflow on a
+number of nodes equal to the length of the `tpr_list` array, parallelizing each
+simulation across a single node, periodically sharing data via MPI calls across
+the ensemble.
 
-    $ gmxapi_DIR=/Users/eric/gromacs python setup.py install --verbose
+gmxapi is just entering beta, so many more features and more flexibility are to
+come. Feel free to make suggestions or describe your own priorities and research
+needs in the issue tracking system.
 
-Pip and related Python package management tools can be a little too flexible and ambiguous
-sometimes.
-If things get really messed up, try explicitly uninstalling the `gmx` module and its dependencies,
-then do it again and repeat until `pip` can no longer find any version of any of the packages.
+# Installation and getting started
 
-    $ pip uninstall gmx
-    $ pip uninstall cmake
-    ...
+A compatible version of GROMACS must either be already installed or may be installed
+as part of package installation. See [`gromacs-gmxapi`](https://github.com/kassonlab/gromacs-gmxapi)
 
-Successfully running the test suite is not essential to having a working `gmxapi` package.
-We are working to make the testing more robust, but right now the test suite is a bit delicate
-and may not work right, even though you have a successfully built `gmxapi` package. If you
-want to troubleshoot, though, the main problems seem to be that automatic installation of
-required python packages may not work (requiring manual installations, such as with `pip install somepackage`)
-and ambiguities between python versions. The testing attempts to run under both Python 2 and
-Python 3, so you may need to explicitly install packages for each Python installation.
+We recommend installing gmxapi in a Python virtual environment. See [docs/install.rst](docs/install.rst) for details
+or refer to the online [user documentation](http://gmxapi.readthedocs.io/en/latest/).
diff --git a/docs/components/plugins.rst b/docs/components/plugins.rst
index f1a7181997..502b38c90d 100644
--- a/docs/components/plugins.rst
+++ b/docs/components/plugins.rst
@@ -1,7 +1,10 @@
 ====================
 Simulation internals
 ====================
+.. toctree::
+    :hidden:
 
+    ../examples/externalForce
 
 The applied_forces facility implemented for the electric field module has become
 the starting point for discussions on API requirements to allow less tightly
@@ -17,6 +20,8 @@ an interface that prevents misuse, provides the minimal access, and hides the
 implementation sufficiently that external or higher-level code cannot invalidate
 assumptions made for optimizations in the core code.
 
+Simulation plugins are further discussed in :doc:`../examples/externalForce`
+
 Simulation loop
 ===============
 
diff --git a/docs/developerguide.rst b/docs/developerguide.rst
index 3985c3fd5a..ba6d8ff6b7 100644
--- a/docs/developerguide.rst
+++ b/docs/developerguide.rst
@@ -5,6 +5,7 @@ Developer Guide
 
 .. toctree::
 
+    intro
     projectstructure
     design
     components
diff --git a/docs/guides.rst b/docs/guides.rst
deleted file mode 100644
index 637649e983..0000000000
--- a/docs/guides.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-======
-Guides
-======
-
-
-.. toctree::
-
-    userguide
-    developerguide
diff --git a/docs/index.rst b/docs/index.rst
index a7690682d3..180d984da6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,9 +9,8 @@ based on a GROMACS fork hosted at https://bitbucket.org/kassonlab/gromacs
     :maxdepth: 2
     :caption: Documentation sections
 
-    intro
-    guides
-    reference
+    userguide
+    developerguide
     changelog
 
 ..
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 0000000000..4e115a9407
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,381 @@
+=================
+Build and install
+=================
+
+``gmxapi`` comes in three parts. A modified version of GROMACS is necessary,
+available from `github.com/kassonlab/gromacs-gmxapi <https://github.com/kassonlab/gromacs-gmxapi/>`_
+
+Download the Python package from
+`github.com/kassonlab/gmxapi <https://github.com/kassonlab/gmxapi/>`_.
+
+A `sample plugin <https://github.com/kassonlab/sample_restraint>`_ demonstrates extending GROMACS with C++ code to be controlled
+from the Python interface.
+
+We recommend installing the Python package in a virtual environment.
+If not installing in a virtual environment, you may not be able to install
+necessary prerequisites.
+You will need a few packages installed that are hard for gmxpy to install automatically.
+Before proceeding, install / upgrade the Python package for ``cmake``. Note that it is not
+sufficient just to have the command-line CMake tools installed.
+::
+
+    python -m pip install --upgrade pip
+    pip install --upgrade setuptools
+    pip install --upgrade scikit-build
+    pip install --upgrade cmake
+
+If not installing in a virtual environment and not installing as a privileged
+user, you will want to append ``--user`` to the ``pip`` commands.
+(E.g. ``python -m install --upgrade pip --user``)
+
+If you will be running the testing suite, you also need ``virtualenv`` and ``tox``.
+::
+
+    pip install --upgrade tox
+
+You do not need to install the ``gmxapi`` Python package in order to use
+``gromacs-gmxapi`` to build MD plugins, but you will need it to run Python-level
+tests. The Python interface produced by the
+`sample restraint <https://github.com/kassonlab/sample_restraint>`_ is ``gmxapi``
+compatible either way.
+
+For all installation options, instead of a using a separate GROMACS installation,
+you can have gmxapi download and build its own copy of GROMACS. This will simplify
+installation, but may miss optimizations and tweaks that could improve performance
+in HPC environments.
+
+Instead of setting ``gmxapi_DIR``, set ``BUILDGROMACS=TRUE`` at the beginning of the ``pip`` command line.
+
+Python virtual environments
+===========================
+
+In the world of Python, a virtual environment is a Python installation that is self-contained
+and easy to activate or deactivate to allow normal Python use without additional concerns of
+software compatibility.
+
+Several systems of managing virtual environments exist. gmxapi is tested with
+Python 3's built-in virtualenv and the add-on virtualenv package for Python 2.
+
+The following documentation assumes you have installed a compatible version of GROMACS and
+installed it in the directory ``/path/to/gromacs``. Replace ``/path/to/gromacs`` with the actual
+install location below.
+
+Anaconda
+~~~~~~~~
+
+Get and install `Anaconda <https://docs.anaconda.com/anaconda/install/>`_.
+Alternatively, on an HPC system
+it may already be provided with a ``module`` system. For example::
+
+    $ module load gcc
+    $ module load cmake
+    $ module load anaconda3
+    $ module load openmpi
+
+You don't have to follow all of the instructions for setting up your login profile if you don't want to,
+but if you don't, then the ``conda`` and ``activate`` commands below will have to be prefixed by your
+conda installation location. E.g. ``~/miniconda3/bin/conda info`` or ``source ~/miniconda3/bin/activate myEnv``
+
+Create a conda virtual environment. Replace ``myEnv`` below with whatever convenient name you choose.
+::
+
+    $ conda create -n myGmxapiEnv python=3 pip setuptools cmake networkx mpi4py
+
+Activate, or enter the environment.
+::
+
+    $ source activate myGmxapiEnv
+
+Install the GROMACS gmxapi fork.
+::
+
+    $ git clone https://github.com/kassonlab/gromacs-gmxapi.git gromacs
+    $ mkdir build
+    $ cd build
+    $ cmake ../gromacs -DGMX_GPU=OFF -DGMX_THREAD_MPI=ON -DCMAKE_CXX_COMPILER=`which g++` -DCMAKE_C_COMPILER=`which gcc` -DCMAKE_INSTALL_PREFIX=$HOME/gromacs-gmxapi
+    $ make -j12 && make install
+    $ source $HOME/gromacs-gmxapi/bin/GMXRC
+
+Make sure dependencies are up to date.
+::
+
+    $ python -m pip install --upgrade pip
+    $ pip install --upgrade setuptools
+    $ pip install --upgrade scikit-build cmake networkx
+    $ MPICC=`which mpicc` pip install --upgrade mpi4py
+    $ git clone
+
+Install the Python module.
+::
+
+    $ git clone https://github.com/kassonlab/gmxapi.git gmxapi
+    $ cd gmxapi
+    $ CC=`which gcc` CXX=`which g++` pip install .
+
+Note: we do not yet have a robust suggestion for setting up `tox` for running the test suite in a conda environment.
+If you come up with a recipe, please let us know. Otherwise, don't worry if you are able to install
+the package but can't get weird errors when you try to run the tests with tox. Instead, just use `pytest` or run the tests in a regular
+(non-conda) Python virtualenv or no virtualenv at all.
+
+virtualenv
+~~~~~~~~~~
+
+For the ensemble simulations features, you will need an MPI installation. On an HPC system, this means you will probably have to use ``module load`` to load a compatible set of MPI tools and compilers. Check your HPC documentation or try ``module avail`` to look for an ``openmpi``, ``mpich``, or ``mvapich`` module and matching compiler module. This may be as simple as
+::
+
+    $ module load gcc
+    $ module load mpicc
+
+Note that the compilers loaded might not be the first compilers discovered automatically by the build tools we will use below, so you may have to specify compilers on the command line for consistency. It may be necessary to require that GROMACS, gmxapi, and the sample code are built with the same compiler(s).
+
+Create a Python virtual environment.
+If using Python 2, use the ``virtualenv`` module. If it is initially not found, install it with ``python -m pip install virtualenv --user``. Then,
+::
+
+    $ python -m virtualenv $HOME/myvenv
+
+For Python 3, use the ``venv`` module.
+::
+
+    $ python -m venv $HOME/myvenv
+
+Activate the virtual environment. Your shell prompt will probably be updated with the name of the environment you created to make it more obvious.
+::
+
+    $ source $HOME/myvenv/bin/activate
+    (myvenv)$
+
+Don't do it now, but you can deactivate the environment by running ``deactivate``.
+
+Update your environment and install some dependencies.
+::
+
+    (myvenv)$ python -m pip install --upgrade pip
+    (myvenv)$ pip install --upgrade setuptools
+    (myvenv)$ pip install --upgrade scikit-build cmake networkx
+
+For MPI, we use mpi4py. Make sure it is using the same MPI installation that we are building GROMACS against and building with compatible compilers.
+::
+
+    (myenv)$ MPICC=`which mpicc` pip install --upgrade mpi4py
+
+If you will be running the testing suite, you also need ``virtualenv`` and ``tox``.
+::
+
+    (myenv)$ pip install --upgrade tox
+
+Get a copy of this repository, if you haven't already. For a released version, you can just download a source package.
+::
+
+    (myenv)$ wget https://github.com/kassonlab/gmxapi/archive/v0.0.4.zip
+    (myenv)$ unzip v0_0_4.zip
+    (myenv)$ cd gmxapi-v0_0_4
+
+For a development branch, you should probably clone the repository. You may not already have ``git`` installed on your system or you may need to load a module for it on an HPC system, which you will need to do before trying the following.
+::
+
+    (myenv)$ git clone https://github.com/kassonlab/gmxapi.git
+    (myenv)$ cd gmxapi
+
+For simplicity, let this package build and install a local GROMACS for you by setting the BUILDGROMACS environment variable. To be on the safe side, make sure to give hints to use the compilers you intend.
+For instance, if we loaded a gcc module, help make sure pip doesn't default to the system ``/bin/cc`` or some such.
+::
+
+    (myenv)$ BUILDGROMACS=TRUE CC=`which gcc` CXX=`which g++` pip install .
+
+This will take a while because it has to download and install GROMACS as well. If you want more visual stimulation, you can add ``--verbose`` to the end of the pip command line.
+
+Python setuptools with existing or shared GROMACS installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure that you have GROMACS installed with the gmxapi library.
+See https://github.com/kassonlab/gromacs-gmxapi
+and load the appropriate gmxrc or note the installation location
+(``/Users/eric/gromacs`` in the following example).
+
+Download this repository and indicate to python where to look for a local GROMACS installation.
+Either first source the GMXRC as described in GROMACS documentation or provide a hint on the command line.
+::
+
+    $ git clone https://github.com/kassonlab/gmxapi.git
+    $ cd gmxapi
+
+Then, if you have sourced your gmxrc or exported GROMACS environment variables, you can just
+::
+
+    $ python setup.py install
+
+or::
+
+    $ pip install --upgrade .
+
+Otherwise, you need to tell Python where to find GROMACS with an environment variable.
+Note that in ``bash``, there must not be spaces between the variable name and the equals sign (``=``).
+::
+
+    $ gmxapi_DIR=/Users/eric/gromacs python setup.py install
+
+..  This line intentionally left blank
+
+or::
+
+    $ gmxapi_DIR=/Users/eric/gromacs pip install --upgrade .
+
+If you have not installed GROMACS already or if ``gmxapi_DIR`` does not contain directories like
+``bin`` and ``share`` then you will get an error along the lines of the following.
+::
+
+   CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
+      Could not find a package configuration file provided by "gmxapi" with any
+      of the following names:
+
+        gmxapiConfig.cmake
+        gmxapi-config.cmake
+
+      Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
+      "gmxapi_DIR" to a directory containing one of the above files.  If "gmxapi"
+      provides a separate development package or SDK, be sure it has been
+      installed.
+
+If you are not a system administrator you are encouraged to install in a Python virtual environment,
+created with virtualenv or Conda.
+Otherwise, you will need to specify the ``--user`` flag to install to your home directory.
+
+Documentation
+=============
+
+Documentation for the Python classes and functions in the gmx module can
+be accessed in the usual ways, using ``pydoc`` from the command line or
+``help()`` in an interactive Python session.
+
+Additional documentation can be browsed on
+`readthedocs.org <http://gmxapi.readthedocs.io/en/readthedocs/>`__ or
+built with Sphinx after installation.
+
+To build the user documentation locally, first make sure you have sphinx
+installed, such as by doing a ``pip install sphinx`` or by using
+whatever package management system you are familiar with. You may also
+need to install a ``sphinx_rtd_theme`` package.
+
+Build *and install* the gmx module.
+
+Then decide what directory you want to put the docs in and call
+``sphinx-build`` to build ``html`` docs from the configuration in the
+``docs`` directory of the gmxpy repository.
+
+Assuming you downloaded the repository to ``/path/to/gmxapi`` and you
+want to build the docs in ``/path/to/docs``, do
+
+::
+
+    sphinx-build -b html /path/to/gmxapi/docs /path/to/docs
+
+or
+
+::
+
+    python -m sphinx -b html /path/to/gmxapi/docs /path/to/docs
+
+Then open ``/path/to/docs/index.html`` in a browser.
+
+Note:
+
+If you try to run ``sphinx-build`` from the root directory of the
+repository, it will get confused and not realize that it should use the
+package you just installed instead of the unbuilt source code.
+Therefore, I recommend the following complete procedure to download,
+install, and build docs for the ``gmxapi`` package::
+
+    $ python -m pip install --upgrade pip
+    $ pip install --upgrade setuptools
+    $ pip install --upgrade cmake
+    $ pip install --upgrade sphinx
+    $ pip install --upgrade sphinx_rtd_theme
+    $ git clone https://github.com/kassonlab/gmxapi.git
+    $ cd gmxapi
+    $ gmxapi_DIR=/path/to/gromacs pip install .
+    $ cd docs
+    $ python -m sphinx -b html . ../html
+    $ cd ..
+    $ open html/index.html
+
+Note that the periods ‘.’ and ‘..’ in the above commands are important
+and that there are no spaces before or after the equals sign (‘=’) when
+specifying the GROMACS path.
+
+Testing
+=======
+
+Unit tests are performed individually with ``pytest`` or as a full
+installation and test suite with ``tox``.
+
+From the root of the repository::
+
+    $ gmxapi_DIR=/path/to/gromacs tox
+
+For pytest, first install the package as above. Then,
+
+::
+
+    $ pytest --pyargs gmx -s --verbose
+
+For a more thorough test that includes the parallel workflow features,
+make sure you have MPI set up and the ``mpi4py`` Python package.
+
+::
+
+    mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose
+
+Note: ``tox`` may get confused when it tries to create virtual
+environments when run from within a virtual environment. If you get
+errors, try running the tests from the native Python environment or a
+different virtual environment manager (i.e. not conda). And let us know
+if you come up with any tips or tricks!
+
+Troubleshooting
+===============
+
+Two of the easiest problems to run into are incompatible compilers and
+incompatible Python. Try to make sure that you use the same C and C++
+compilers for GROMACS, for the Python package, and for the sample
+plugin. These compilers should also correspond to the ``mpicc`` compiler
+wrapper used to compile ``mpi4py``. In order to build the Python
+package, you will need the Python headers or development installation,
+which might not already be installed on the machine you are using. (If
+not, then you will get an error about missing ``Python.h`` at some
+point.) If you have multiple Python installations (or modules available
+on an HPC system), you could try one of the other Python installations,
+or you or a system administrator could install an appropriate Python dev
+package. Alternatively, you might try installing your own Anaconda or
+MiniConda in your home directory.
+
+If an attempted installation fails with CMake errors about missing
+“gmxapi”, make sure that Gromacs is installed and can be found during
+installation. For instance,
+
+::
+
+    $ gmxapi_DIR=/Users/eric/gromacs python setup.py install --verbose
+
+Pip and related Python package management tools can be a little too
+flexible and ambiguous sometimes. If things get really messed up, try
+explicitly uninstalling the ``gmx`` module and its dependencies, then do
+it again and repeat until ``pip`` can no longer find any version of any
+of the packages.
+
+::
+
+    $ pip uninstall gmx
+    $ pip uninstall cmake
+    ...
+
+Successfully running the test suite is not essential to having a working
+``gmxapi`` package. We are working to make the testing more robust, but
+right now the test suite is a bit delicate and may not work right, even
+though you have a successfully built ``gmxapi`` package. If you want to
+troubleshoot, though, the main problems seem to be that automatic
+installation of required python packages may not work (requiring manual
+installations, such as with ``pip install somepackage``) and ambiguities
+between python versions. The testing attempts to run under both Python 2
+and Python 3, so you may need to explicitly install packages for each
+Python installation.
diff --git a/docs/reference.rst b/docs/reference.rst
index d18bdd7d4a..3f861ad78d 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -1,20 +1,10 @@
-=========
-Reference
-=========
-
-.. toctree::
-    :hidden:
-
-    reference/python.rst
-
-Concise reference documentation extracted directly from code.
-For more curated instruction, see the :doc:`userguide` and :doc:`developerguide`.
+===========================
+gmx Python module reference
+===========================
 
+.. Concise reference documentation extracted directly from code.
 .. For new and non-backwards-compatible features, API versions must be given.
 
-Python module reference
-=======================
-
 The Gromacs Python interface is implemented as a high-level scripting interface implemented in pure Python and a lower-level API implemented as a C++ extension.
 The pure Python implementation provides the basic ``gmx`` module and
 classes with a very stable syntax that can be maintained with maximal compatibility
@@ -22,19 +12,46 @@ while mapping to lower level interfaces that may take a while to sort out. The
 separation also serves as a reminder that different execution contexts may be
 implemented quite diffently, though Python scripts using only the high-level
 interface should execute on all. Bindings to the ``libgromacs`` C++ API are
-provided in the submodule ``gmx.core``.
+provided in the submodule :module:`gmx.core`.
+
+The following documentation is extracted from the ``gmx`` Python module and is also available
+directly, using either ``pydoc`` from the command line or ``help()`` from within Python, such
+as during an interactive session.
+
+Refer to the Python source code itself for additional clarification.
+
+.. testsetup::
+
+    import gmx
+    from gmx.data import tpr_filename
+
+.. automodule:: gmx
+
+.. automodule:: gmx.system
+    :members:
+
+.. automodule:: gmx.workflow
+    :members:
+
+.. automodule:: gmx.context
+    :members:
+
+.. automodule:: gmx.status
+    :members:
+
+.. automodule:: gmx.exceptions
+    :members:
+
+.. automodule:: gmx.core
+
+.. skipping gmx.core.md_from_tpr
 
-:doc:`reference/python`
+.. autoclass:: gmx.core.MDSystem
+    :members:
 
-C++ API reference
-=================
+.. autoclass:: gmx.core.Status
+    :members:
 
-Documentation extracted for public C++ API. All symbols and names appearing in
-the public API headers must be documented to the extent of their visibility to
-external code. Design details are described in the :doc:`developerguide`
-and more implementation details may be available separately in the library
-documentation. If the API components are built in developer mode, links are
-provided for classes that provide additional interfaces to library code. All
-documentation must indicate relevant API versions.
+.. autoclass:: gmx.core.MDModule
+    :members:
 
-`CPP docs <../doxygen/api-user/html/group__gmxapi.html>`_
diff --git a/docs/reference/python.rst b/docs/reference/python.rst
deleted file mode 100644
index 16b18ff1bc..0000000000
--- a/docs/reference/python.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-===========================
-gmx Python module reference
-===========================
-
-The following documentation is extracted from the ``gmx`` Python module and is also available
-directly, using either ``pydoc`` from the command line or ``help()`` from within Python, such
-as during an interactive session.
-
-Refer to the Python source code itself for additional clarification.
-
-.. testsetup::
-
-    import gmx
-    from gmx.data import tpr_filename
-
-.. automodule:: gmx
-
-.. automodule:: gmx.system
-    :members:
-
-.. automodule:: gmx.workflow
-    :members:
-
-.. automodule:: gmx.context
-    :members:
-
-.. automodule:: gmx.status
-    :members:
-
-.. automodule:: gmx.exceptions
-    :members:
-
-.. automodule:: gmx.core
-
-.. skipping gmx.core.md_from_tpr
-
-.. autoclass:: gmx.core.MDSystem
-    :members:
-
-.. autoclass:: gmx.core.Status
-    :members:
-
-.. autoclass:: gmx.core.MDModule
-    :members:
-
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000000..f6b9f191dd
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,61 @@
+================
+Python interface
+================
+
+The primary user interface provided through ``gmxapi`` is a Python module
+called ``gmx``. The interface is designed to be maximally portable to different
+execution environments, with an API that can be used and extended from Python or
+C++.
+
+For full documentation of the Python-level interface and API, use the ``pydoc``
+command line tool or the ``help()`` interactive Python function, or refer to
+the :doc:`reference` documentation.
+
+Once the ``gmxapi`` package is installed, running simulations is easy.::
+
+    import gmx
+    md = gmx.workflow.from_tpr(tpr_filename)
+    gmx.run(md)
+
+To run a batch of simulations, just pass an array of inputs.::
+
+    import gmx
+    md = gmx.workflow.from_tpr([tpr_filename1, tpr_filename2, ...])
+    gmx.run(md)
+
+If additional arguments need to be provided to the simulation as they would for
+the ``mdrun`` command line tool, you can add them to the workflow specification
+when you create the MD work element.::
+
+    md = gmx.workflow.from_tpr(tpr_list, tmpi=20, grid=[3, 3, 2], ntomp_pme=1, npme=2, ntomp=1)
+
+Python does not wrap a command-line tool, so once installation is complete,
+there shouldn't be any additional configuration necessary, and any errors that
+occur should be caught at the Python level. Exceptions should all be descendents
+of `gmx.exceptions.Error`.
+
+If you have written plugins or if you have downloaded and built the
+`sample <https://github.com/kassonlab/sample_restraint>`_ plugin, you attach it
+to your workflow by making it a dependency of the MD element. The following
+example applies a harmonic spring restraint between atoms 1 and 4::
+
+    import gmx
+    import myplugin
+    assert gmx.__version__ == '0.0.5'
+
+    md = gmx.workflow.from_tpr([tpr_filename])
+    params = {'sites': [1, 4],
+              'R0': 2.0,
+              'k': 10000.0}
+    potential_element = gmx.workflow.WorkElement(namespace="myplugin",
+                                                 operation="create_restraint",
+                                                 params=params)
+    potential_element.name = "harmonic_restraint"
+    md.add_dependency(potential_element)
+    gmx.run(md)
+
+Refer to the `sample <https://github.com/kassonlab/sample_restraint>`_ plugin
+for an additional example of an ensemble-restraint biasing potential that
+accumulates statistics from several trajectories in parallel to refine a
+pair restraint to bias for a target distribution.
+
diff --git a/docs/userguide.rst b/docs/userguide.rst
index 05090c6862..5f8c2eb446 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -2,113 +2,8 @@
 User Guide
 ==========
 
-Build and install
-=================
-
-Download the repository from
-`github.com/kassonlab/gmxapi <https://github.com/kassonlab/gmxapi/>`_
-and refer to the ``README.md`` file for details.
-
-Also see
-
 .. toctree::
 
-    examples/externalForce
-
-How to
-======
-
-..
-    links to documentation by example begin as user stories.
-    Cross-link with components doc (feature) when possible.
-    Unavailable workflows belong in a scrum board or issue tracking system, but
-    are too noisy for the main Gromacs Redmine. For the moment, curate them here
-    to clarify targeted features.
-
-The following is a template of planned functionality that will link to documentation-by-example in the future.
-
-As a Python user
-----------------
-
-Use bottled workflows / tasks
-so that I can get going quickly.
-
-Access coordinates from a trajectory file
-so that I can use my favorite Python-based analysis tool.
-
-Pass non-file-backed trajectory data to and from the MD engine
-so that I can avoid filesystem overhead.
-
-Transform a PDB record to a model suitable for a Gromacs input record
-so that I can use molecular data from a common source.
-
-Run -> analyze -> run in a pipeline
-so that filesystem and MPI overhead is avoided
-
-Sanity-check my input parameters
-so that I can avoid precision or other numerical errors or known bad physics leading to invalid simulation results (e.g. as provided by grompp)
-
-
-As an advanced workflow
------------------------
-Have flexible ways to represent/pass data BLOBs and streams
-so that I can adapt to native APIs for containers, workflow managers, and other cyberinfrastructure.
-
-Deal with proxy objects
-so that I don't trigger unnecessary communications across successive API calls.
-
-Coordinate batches of simulation results or trajectory streams
-so that I can asynchronously configure and launch the next simulation ASAP.
-
-Define data flow or graphs for deferred execution
-so that I can let lower level software optimize execution and communications.
-
-Rely on robust checkpointing of data graph state
-so that I can avoid duplicated computation after network interruptions or job failure.
-
-Include simulation and analysis tasks in the same data graph
-so that I can use a single, simpler interface.
-
-As an API client
-----------------
-Manipulate simulation box and atom configuration
-so that I can solvate, adjust ions, or set periodic boundary conditions
-
-Separate core module parameters from user interface so that I can process options
-without additional API calls.
-
-Make a set of well-defined changes to a template of simulation input
-so that I can systematically prepare the next batch of (uncoupled) simulations.
-
-Compute the potential energy for a provided atom configuration
-so that I can analyze a single configuration easily.
-
-Measure the potential energy of a given Selection and force field during a simulation
-so that I can compare force fields or perform analyses
-
-Retrieve microstate data from a live (or paused) simulation
-so that I can assure the mapping between calculations performed within and outside of Gromacs regardless of trajectory file format conventions, restrictions, or overhead.
-
-Produce/edit a topology through a high-level interface
-so that I can use optimized Gromacs kernels without constraint to a compiled force field implementation.
-
-Use a concurrency API in conjunction with the Gromacs API
-so that I can take advantage of parallelism and data locality optimizations from versatile external code.
-
-As a plugin
------------
-
-Apply an :doc:`examples/externalForce` to an atom selection
-so that I can implement additional physics.
-
-Define new potentials by implementing a simple interface
-so that I can access native Gromacs parallelism and generalizable optimizations.
-
-Access objects passed in by the user
-so that workflow-scope parameters can be managed in a single place.
-
-Access contributions of individual force field components (potentials) to calculated values
-so that model details are accessible with consistent semantics.
-
-Request, access, and announce data through an interface to the library communicator(s)
-so that I can have the local data I need without the ability to trigger communication.
+    install
+    usage
+    reference
diff --git a/src/gmx/__init__.py b/src/gmx/__init__.py
index abfd3846fd..65a9c686f8 100644
--- a/src/gmx/__init__.py
+++ b/src/gmx/__init__.py
@@ -33,8 +33,8 @@
 Installation
 ------------
 
-Download the ``gmxpy`` repository from https://github.com/kassonlab/gmxapi and refer
-to the README.md file for details on installing this Python module.
+Download the repository from https://github.com/kassonlab/gmxapi and refer
+to `docs/install.rst <./install.html>`_ for details on installing this Python module.
 
 The gmxapi library must be installed to build and install the gmx module.
 Retrieve the GROMACS fork from https://github.com/kassonlab/gromacs-gmxapi and

From b2ea40111d91ce722553b164e8fe00e68743ec19 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Sat, 28 Apr 2018 21:05:42 +0300
Subject: [PATCH 11/13] Add Dockerfile for reproducible environments.

---
 docker/Dockerfile | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 docker/Dockerfile

diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 0000000000..59a0c2c79e
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,31 @@
+# Build container for gmxapi/gmxapi:<tag>
+# Initially we will use a tmpi libgromacs and openmpi mpi4py
+
+FROM gmxapi/gromacs-gmxapi:0.0.5
+
+# Allow build for an arbitrary branch or tag, but default to the tip of `master`
+ARG BRANCH=master
+
+RUN conda install pytest tox cmake
+
+# At least one conda release does not leave tox executable...
+# However, tox doesn't seem to be helping us here...
+# RUN chmod a+x /opt/conda/bin/tox
+
+# Note default for the base image at this point is Python3
+RUN pip install --upgrade pip && \
+    pip install sphinx mpi4py
+
+RUN pip install --upgrade setuptools --user
+
+#ADD --chown=1000:100 gmxpy /home/jovyan/gmxpy
+
+RUN wget https://github.com/kassonlab/gmxapi/archive/$BRANCH.zip && \
+    unzip $BRANCH.zip && \
+    mv gmxapi-$BRANCH /home/jovyan/gmxpy
+
+RUN (cd /home/jovyan/gmxpy && \
+    gmxapi_DIR=/home/jovyan/install/gromacs pip install . --upgrade --verbose)
+
+# Test with
+#    docker run --rm -ti gmxapi/gmxapi bash -c "cd gmxpy && mpiexec -n 2 python -m mpi4py -m pytest  --log-cli-level=DEBUG --pyargs gmx -s --verbose"

From bc1feaebdc2fc9459c4f6b21851d27b01218e115 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Mon, 30 Apr 2018 14:13:34 +0300
Subject: [PATCH 12/13] update source URL for Travis-CI build.

---
 .travis.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index aaaf34cc97..0ccea9935f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -40,11 +40,11 @@ before_install:
   - apt list --installed
   - test -n $CC  && unset CC
   - test -n $CXX && unset CXX
-  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/dev_5.zip
-  - unzip dev_5.zip
+  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/master.zip
+  - unzip master.zip
 
 install:
-  - pushd gromacs-gmxapi-dev_5
+  - pushd gromacs-gmxapi-master
   - mkdir build
   - pushd build
   - cmake -DCMAKE_INSTALL_PREFIX=$HOME/gromacs -DGMX_FFT_LIBRARY=fftpack -DGMX_GPU=OFF -DGMX_OPENMP=OFF -DGMX_SIMD=None -DGMX_USE_RDTSCP=OFF -DGMX_MPI=$GMX_MPI -DGMX_THREAD_MPI=$GMX_THREAD_MPI ..

From 7b6b77722213fddff51087b4b9cee9e3c7a77fa1 Mon Sep 17 00:00:00 2001
From: "M. Eric Irrgang" <ericirrgang@gmail.com>
Date: Mon, 30 Apr 2018 14:14:04 +0300
Subject: [PATCH 13/13] minor clean-up in Dockerfile

---
 docker/Dockerfile | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docker/Dockerfile b/docker/Dockerfile
index 59a0c2c79e..5e8ef3e2ec 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -22,10 +22,11 @@ RUN pip install --upgrade setuptools --user
 
 RUN wget https://github.com/kassonlab/gmxapi/archive/$BRANCH.zip && \
     unzip $BRANCH.zip && \
-    mv gmxapi-$BRANCH /home/jovyan/gmxpy
+    mv gmxapi-$BRANCH /home/jovyan/gmxpy && \
+    rm $BRANCH.zip
 
 RUN (cd /home/jovyan/gmxpy && \
     gmxapi_DIR=/home/jovyan/install/gromacs pip install . --upgrade --verbose)
 
 # Test with
-#    docker run --rm -ti gmxapi/gmxapi bash -c "cd gmxpy && mpiexec -n 2 python -m mpi4py -m pytest  --log-cli-level=DEBUG --pyargs gmx -s --verbose"
+#    docker run --cpus 2 --rm -ti gmxapi/gmxapi bash -c "cd gmxpy && mpiexec -n 2 python -m mpi4py -m pytest  --log-cli-level=DEBUG --pyargs gmx -s --verbose"