* Introduction & Features

** Weighted Ensemble (WE)

# TODO

.. TODO For a background to weighted ensemble see: 


** Features

- State of the art WE resamplers: WExplore and REVO
- Super fast molecular dynamics via OpenMM
- Purpose built HDF5 storage format for WE data: ~WepyHDF5~
- Analysis routines for:
  - free energy profiles
  - rate calculations
  - computing trajectory observables
  - extracting linear trajectories from clone-merge trees
  - conformation state networks such as Markov State Models (MSMs)
  - aggregating multiple runs
- Orchestration framework for managing large number of simulations
  with simulation checkpointing, recovery, and continuations.
- Expert friendly: Fully-featured framework for building and
  customizing simulations for exactly what you need.
- Leverage the entire python ecosystem, you're limited to an old
  version of an embedded interpreter.
- No complex /ad hoc/ configuration files, everything is python.


#+begin_export rst
  .. _resources:
#+end_export

** Getting Started

Once you have wepy @@rst::any:`installed <installation>`@@ you can
check out the @@rst::any:`quickstart <quick_start>`@@ to get a rough
idea of how it works.

Then you can either read the @@rst::any:`user's guide <users_guide>`@@
or head on to the @@rst::any:`tutorials <tutorials/index>`@@ or execute the
[[https://github.com/ADicksonLab/wepy/tree/master/info/examples][examples]].

For a complete description of the modules and their components check
out the @@rst::any:`API documentation <api>`@@.


** Compatibility

Tested succesfully with:

| Python | OpenMM | Pass |
|--------+--------+------|
|    3.6 |  7.4.1 | ✓    |
|    3.6 |  7.3.1 | ✓    |
|    3.7 |  7.4.1 | ✓    |
|    3.7 |  7.3.1 | ✓    |
|    3.8 |  7.4.1 | ✗    |
|    3.8 |  7.3.1 | ✗    |

Using the ~omnia~ channel ~openmm~, e.g.:

#+begin_src bash
conda install -c omnia openmm=7.4.1
#+end_src

See the ~noxfile.py~ for full test matrix.

** Contributed wepy libraries and other useful resources

Here is a list of packages that are not in the main ~wepy~ repository
but may be of interest to users of wepy.

These include things like :

- distance metrics and boundary conditions for different kinds of
  systems
- resampler and runner prototypes
- related analysis or utility libraries


They are:


- [[https://github.com/ADicksonLab/geomm][geomm]] :: purely functional library for common numerical routines in
        computational biology and chemistry, with no dependency on
        specific file or topology formats.

- [[https://github.com/ADicksonLab/wepy-developer-resources][wepy-developer-resources]] :: Unofficial and miscellaneous materials
  related to wepy, including talks, workshops, contributed tutorials
  etc. May be out of date.

- [[https://github.com/ADicksonLab/wepy/blob/master/sphinx/source/introduction.org][mastic]] :: Library for doing general purpose "profiling" of
  intermolecular interactions. Useful for computing observables an
  experimental chemist understands. Also useful for building distance
  metrics.

- [[https://github.com/mdtraj/mdtraj][mdtraj]] :: Excellent library with optimized code for numerical
  routines of interest in computational biology and chemistry. Differs
  from geomm in that it relies on their own topology format. The
  WepyHDF5 JSON topology format is borrowed from this library. Used in
  wepy as a utility writer of commonly used formats like PDBs, DCDs,
  etc.

- [[https://github.com/choderalab/openmmtools][openmmtools]] :: Contributed components for OpenMM. Contains some
  ready-made test systems that are very convenient for testing and
  prototyping components in wepy.

- [[https://github.com/ADicksonLab/openmm_systems][openmm-systems]] :: A friendly fork of ~openmmtools~ that just
  provides the test systems for ease of installation. We depend on
  this for our examples and testing.

- [[https://github.com/ADicksonLab/CSNAnalysis][CSNAnalysis]] :: small library for aiding in the analysis of
  conformation state networks (CSNs) which can be generated from
  ~wepy~ data.



** Alternatives

~wepy~ is not the only WE framework package. Other packages have
different scopes and features. I have tried to provide a fair
comparison of ~wepy~ to them to help potential users make an informed
decision. If you feel a package is misrepresented contact the ~wepy~
devs or submit a pull request with your desired changes.

**** [[https://github.com/westpa/westpa][WESTPA]]

Weighted ensemble package in Python 2.7. More reliant and integrated
with unix-like operating systems providing modularity through shell
scripting and python modules.

As an older project it has support for more MD engines (and non-MD
stochastic sampling engines, e.g. BioNetGen) and is currently better
suited for running simulations on large numbers of CPUs in a clustered
environment.

Support for WE algorithms closer to the original paper by Huber and
Kim with a focus on static tesselation of conformational space.

Has some support for adaptive binning algorithms like WExplore, but it
is a little more challenging to develop radically different resamplers
like REVO, which have no concept of bins at all.


**** [[http://ccl.cse.nd.edu/software/awe/][AWE: Accelerated Weighted Ensemble]]

Another Python 2 library with a focus on the Accelerated WE resampling
algorithm and integration with a Work Queue library for distributed
jobs.




