edeustua / wepy

Weighted Ensemble simulation framework in Python (Mirror of main private development repo. After the main release the development of the project will become public.)

Weighted Ensemble Python (wepy)

Modular implementation and framework for running weighted ensemble simulations in pure python, where the aim is to have simple things simple and complicated things possible. The latter being the priority.

The goal of the architecture is that it should be highly modular to allow extension, but provide a “killer app” for most uses that just works, no questions asked.

Comes equipped with support for OpenMM molecular dynamics, parallelization using multiprocessing, the WExplore and REVO (Resampling Ensembles by Variance Optimization) resampling algorithms, and an HDF5 file format and library for storing and querying your WE datasets that can be used from the command line.

The deeper architecture of wepy is intended to be loosely coupled, so that unforeseen use cases can be accomodated, but tightly integrated for the most common of use cases, i.e. molecular dynamics.

This allows freedom for fast development of new methods.

Also see the full introduction.

Community

Discussion takes place on riot.im (#wepy:matrix.org) which is a slack-like app that works on the Matrix protocol: https://riot.im/app/#/room/#wepy:matrix.org

You can also contact me directly:

[e-mail]

Installation

Also see: Installation Instructions

To install from pip (which may be out of date):

pip install wepy[all]

Which will install most dependencies.

To install the optional, but likely desired feature, OpenMM you should probably just use the omnia channel on conda, otherwise you will need to compile it yourself.

conda install -c omnia openmm

There are some optional features you can install as well using the “extras” spec in pip. The base package aims to be very easy to install but lacks a lot of functionality that makes wepy truly useful. Currently, these are:

mdtraj

allows export of structures to the mdtraj format which has many writers for serialization, e.g. pdb, dcd, etc.

all

installs all extras

Check the setup.py file under ‘extras_requirements’ for the full listing.

pip install wepy[mdtraj]

You can always install from git as well for the latest:

pip install git+https://github.com/ADicksonLab/wepy.git

If installation went alright you should have this command line interface for working with orchestration available:

wepy --help

Using automation tool

You can also try some of the scripting and automation tools the wepy repo uses.

For this you will need the invoke package (which we use kind of like the make tool).

So either install invoke via pip how you normally would on your system:

pip3 install invoke

Or source the bootstraph.sh file which will infer the directory you have installed anaconda in and install invoke to the base environment there:

. tooling.sh

Note if you don’t use the bootstrap config here you will have to set the ‘ANACONDA_DIR’ environmental variable in your shell for the automation to work properly. This can be done temporarily like in the bootstrap.sh configuration file, but probably you should be doing this in your shell configs.

Then you can run tasks via the invoke command line ‘inv’. To list the available tasks and their descriptions run:

inv -l

Getting Started

ATTENTION: these parts of the documentation are under construction now. Please check back for updates.

For a very quick sketch of how to use wepy see the quickstart.

It is recommended to read the User’s Guide before starting to use wepy, especially if you are new to programming or only have experience with older simulation engines and packages, as it will focus your attention on the relevant aspects.

If you are competent in object-oriented programming and python you can probably skip the first sections and head straight to the outline of simulation manager and its components in the user’s guide.

Otherwise you can head straight to the tutorials and examples.

The tutorials are ipython notebooks while the examples are collections of scripts showing you how you might actually run wepy in production.

There is an example with a pair of Lennard-Jones particles that runs on the reference implementation. This is the “Hello World” example and should be your starting point.

A more advanced (and interesting) example is a non-equilibrium unbinding WExplore simulation of the soluble epoxide hydrolase (sEH) protein with the inhibitor TPPU, which was the subject of this paper:

Lotz and Dickson. 2018. JACS 140 (2) pp. 618-628 (DOI: 10.1021/jacs.7b08572)

If you plan developing wepy read the Dev Guide.