Added preliminaries.

For this workshop, you'll want to have a developer install of
OpenPathSampling. Note that OPS only runs on Mac and Linux, and only in
Python 2.7. (That is, it does not work with Windows or with Python 3).
Setting up a developer installation involves two major steps: installing the
requirements, and installing OPS from a git repository.
# Conda-based installation
We strongly recommend using `conda` to set up your Python installation.
Unless you're already using a highly customized Python setup, you will
probably prefer to work with `conda`.
You can download and install `conda` from
Note that you should get the version for Python 2.7.
## Installing the requirements
Add the `omnia` channel to your `conda` environment with:
conda config --add channels
To install the requirements for OPS, we'll first install OPS with `conda`
(which automatically installs its requirements), and then remove OPS
(leaving the requirements behind). Note that you don't want to use the
`conda`-installed version of OPS, because then you won't be able to get any
changes we make during the workshop!
conda install openpathsampling
conda remove openpathsampling
For this workshop, you should also install `jupyter`, which provides an
interactive interface for OPS (and Python in general), and which we use for
our examples.
conda install jupyter
## Developer install of OpenPathSampling
You'll want a developer install of OPS (that is, an editable installation
from a git repository) because that enables us to rapidly add a fix to the
core code for any issues you come across while developing. Once you have the
requirements, it is very easy to do this installation.
<!-- BREAK -->
### Optional: Make a fork
If you think you're interested in making changes to the core of OPS (rather
than just creating external modules) you should make a fork of OPS. Log into
GitHub, go to
and click on the "Fork" button in the upper right. In this case, you should
also [add an SSH key to your GitHub
Note that, for the workshop, you should not edit core OPS and only create
external modules. Some of these will be added the core of OPS later.
### Clone and install
If you made a fork, clone it with:
git clone
If you did not make a fork, clone the main repository with:
git clone
Either way, cloning the repository will download a directory called
`openpathsampling/`. Change into that directory, and you should see (along
with several other things) a file called ``. That means you're in
the right place. Install OPS with the command:
pip install -e .
Depending on your Python setup, you may need to `sudo` that. Test that
everything works by running the command `nosetests` from that directory.
# The hard way: Manual installation
If you don't want to use `conda`, you'll have to install the requirements
Most package managers (macports, yum, apt-get) have packages for the
scientific python stack. Some of these may also be `pip`-installable. You'll
* python 2.7
* numpy
* scipy
* pandas
* nose
* jupyter
* netcdf4
* matplotlib
You will need to manually install the following:
* [OpenMM](
The following requirements can be `pip`-installed:
* pyyaml
* svgwrite
* mdtraj
* ujson
* networkx
To install with `pip`, use the command `pip install PACKAGENAME`
The following will have to be installed from source:
* [openmmtools](
To install `openmmtools` directly using `pip`, use the command:
pip install git+git://
As mentioned in the `conda`-based install, you should also install
[`jupyter`]( It isn't required to run OPS, but it will
make many things much easier, and is our recommended approach for developing
Once you have the requirements installed manually, the procedure for a
developer install of OPS is the same as in the `conda` based install above.
Optionally make a fork, then clone and install.
# Possible Projects for ESDW1
Here are descriptions of a few possible projects for the E-CAM Extended
Software Development Workshop, to be held in Traunkirchen, Austria, in
November 2016.
While we encourage participants to bring their own project ideas as well,
we should begin with the tasks which were part of the original description
of the workshop.
The goals of this document are:
1. To describe the purpose of each proposed module
2. To give some sense of how the module will be implemented -- this is
primarily to serve as reference during the workshop
3. To provide references for further reading.
Many of the references to the scientific material are to specific sections
from a [review by Bolhuis and
Dellago]( This document will be
referred to below as "Bolhuis & Dellago Review," with specific section
cited. Participants should have received a PDF of that review along with
this document.
1. Basic Shooting and Shifting
2. Aimless Shooting
3. Reactive Flux
4. Calculation of Transition State Ensemble
5. Maximum Likelihood for Reaction Coordinate
6. Optimal Interface Placement
## Basic Shooting and Shifting
#### What it is
I assume the audience for this is familiar with the basics of path sampling,
so you've heard of the shooting and shifting moves. For this workshop, we'll
describe "basic" shooting and shifting as:
* one-way shooting
* two-way shooting
* shifting without caching previous results
Note that much of the advantage of the original shifting move was that it
cached the previously calculated parts of the trajectory. This would be much
more difficult to implement in OPS. But a simpler version of shifting, where
you recalculate the new frames each time, should be relatively
straightforward to implement.
#### What is needed to implement it
One-way shooting is already implemented, and two-way shooting is on the way.
Things to be implemented at the ESDW would be:
* *shifting*: as mentioned above, without caching is probably best. This
will involve a `ShiftingPathMover` subclass of `EngineMover`, and a
`ShiftingMoveStrategy` subclass of `MoveStrategy`.
* *shooting point modifications*: two-way shooting involves modifying the
shooting point (typically, changing velocities). There are many possible
ways to do this; participants might have some good examples to include.
These will be subclasses of `SnapshotModifier`.
#### What you should read
* Bolhuis & Dellago Review: Section 4; especially 4.4, 4.9
* OPS docs on adding path movers
* OPS docs on snapshot modifiers
## Aimless Shooting
#### What it is
Aimless shooting is a special variant of the shooting move designed to keep
the shooting point near the barrier. The principle is similar to using
biased shooting points, but instead of adding an external bias, aimless
shooting tries to make the center of the trajectory near the top of the
It does this by selecting a frame near the middle of the trajectory (usually
there are 3 specific options) and shooting from that after completely
randomizing the velocities.
#### What is needed to implement it
Aimless shooting will require implementing a few new objects:
* an `AimlessShootingSelector` subclass of `ShootingPointSelector`
* an `AimlessShootingStrategy` subclass of `MoveStrategy`
The approach is that aimless shooting is just a special case of two-way
shooting, with a specific way of selecting the shooting point, and a
specific way of modifying the selected shooting point (`RandomVelocities`,
already implemented).
The `AimlessShootingStrategy` will wrap all of this into a convenient tool
that works well with other parts of OPS.
<!-- BREAK -->
#### What you should read
* Bolhuis & Dellago Review: 4.7
* [Peters and Trout. JCP **125**, 054108
* OPS docs on shooting point selectors
* OPS docs on path movers and move strategies
## Reactive Flux
#### What it is
The reactive flux method, often called the "Bennett-Chandler" method, is one
of the oldest ways to calculate the rate (the idea behind it goes all the
way back to the early years of modern rate theory, with people like Wigner.)
The basic idea is that you start from points at some optimal dividing
surface (ideally, transition state) and shoot with random (Boltzmann)
velocities for some fixed maximum time. Then the behavior of the flux-side
time correlation function gives the rate of the reaction.
#### What is needed to implement it
In many ways, the reactive flux approach is much like the committor
simulation, which is already built into OPS. The main difference is that it
uses a fixed length trajectory instead of accounting for the state the
simulation is in. Just like our existing committor simulation, this should
be treated as shooting from a number of snapshots which are the input
This approach means that any method to select initial points on the dividing
surface could be used. It also means that it would work with a method that
uses a broader dividing "volume" (instead of a "surface") could work -- such
as the "S-shooting" approach recently developed by Menzel, Singraber, and
Dellago. This would require different analysis, but adding the S-shooting
algorithm would be an excellent follow-up module after the Bennett-Chandler
type of reactive flux.
* `ReactiveFluxSimulation` subclass of `PathSimulator`
* `ReactiveFluxAnalysis` class for analysis
* (second module) `SShootingAnalysis` class
#### What you should read
* Bolhuis & Dellago Review: 3.1
* [Menzl, Singraber, and Dellago. Faraday Disc. In
* OPS docs on committor
* OPS docs on shooting point analysis (used to analyze committor)
## Calculation of Transition State Ensemble
#### What it is
The transition state ensemble is the set of points from a TPS calculation
which correspond (approximately) to a committor value of 0.5.
#### What is needed to implement it
* wrapper `PathSimulator` which uses `CommittorSimulation`
* analysis for the results
#### What you should read
* [Geissler, Dellago, and Chandler. J. Phys. Chem. B **103**, 3706
* [Bolhuis, Dellago, and Chandler. Proc. Natl. Acad. Sci. USA **97**, 5877
* OPS docs on path simulators
* OPS docs on shooting point analysis (used to analyze committor)
## Maximum Likelihood for Reaction Coordinate
#### What it is
Peters and Trout developed an approach to use the acceptance and rejection
of shooting points, particularly in the aimless shooting algorithm, to
select the best reaction coordinates from a list of candidates. The approach
used is a general statistical approach called "maximum likelihood
#### What is needed to implement it
This is purely an analysis method. You should take the candidate reaction
coordinates as `CollectiveVariable` objects, and perform the analysis inside
a custom analysis class.
#### What you should read
* Bolhuis & Dellago Review: 7.4
* [Peters and Trout. JCP **125**, 054108
* [Wikipedia on maximum likelihood
* OPS docs on analysis
<!-- BREAK -->
## Optimal Interface Placement
#### What it is
The efficiency of TIS depends on the placement of its interfaces. Since each
extra interface you sample adds an entire ensemble that needs to be
converged, you want as few interfaces as possible. However, the ensembles
associated with each interface need to have enough overlap to give
statistically meaningful results when you use the TIS rate equation to
combine them.
Borrero and Escobedo developed a scheme for optimal placement of interfaces
in FFS, which was later applied to TIS by Borrero, Weinwurm, and Dellago.
The approach is iterative: you run a short TIS, and use the results from
that to determine where the interfaces should be placed for the next round.
#### What is needed to implement it
* Analysis class that takes the (analyzed) `network` and returns a suggested
new network.
* Subclass of `PathSimulator` to automate multiple iterations of analysis
and running with new interface values.
#### What you should read
* [Borrero and Escobedo. JCP **129**, 025115
* [Borrero, Weinwurm, and Dellago. JCP **134**, 244118
* OPS docs on creating a new `PathSimulator`
* OPS docs on running a TIS simulations and analyzing the results
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment