Path Density for OpenPathSampling

Software Technical Information

The information in this section describes OpenPathSampling as a whole. Information specific to the additions in this module are in subsequent sections.

Language
Python (2.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later

Authors: David W.H. Swenson

This module implements path density calculations for OpenPathSampling, including a generic multidimensional sparse histogram, and plotting functions for the two-dimensional case.

Purpose of Module

Path density is one of the useful ways to visualize a path ensemble generated by path sampling. At first glance, a typical path density plot may appear similar to a two-dimensional free energy landscape plot. They are both “heatmap”-type plots, plotting a two-dimensional histogram in some pair of collective variables. However, path density differs from free energy in several important respects:

  • A path density plot is histogrammed according to the number of paths, not the number of configurations. So if a cell is visited more than once during a path, it still only gets counted once.
  • A path density plot may interpolate across cells that the path jumps over. This is because it is assumed that the input must actually be continuous.

These differences can prevent metastable regions from overwhelming the transition regions in the plot. When looking at mechanisms, the path density is a more useful tool than the raw configurational probability.

The implementation in this module includes:

  • A SparseHistogram class for histogramming in arbitrary dimensions (allowing path densities in more than the traditional two dimensional plot). This class can also be used for other purposes (such as free energy histograms).
  • A PathHistogram subclass of SparseHistogram, which includes the options to normalize either per-path or per-configuration, and the tools for interpolating across skipped cells.
  • A PathDensityHistogram subclass of PathHistogram, which includes the ability to convert trajectories to representations of the trajectories in some list of collective variables, and sets reasonable default behavior for normalization and interpolation.
  • A HistogramPlotter2D that is specialized for plotting a 2D histogram, especially a PathDensityHistogram.

Background Information

This module builds on OpenPathSampling, a Python package for path sampling simulations. To learn more about OpenPathSampling, you might be interested in reading:

Testing

Tests in OpenPathSampling use the nose package.

This module has been included in the OpenPathSampling core. Its tests can be run by setting up a developer install of OpenPathSampling and running the command nosetests from the root directory of the repository.

Examples

The examples below link to both a notebook (in the OpenPathSampling GitHub repository) and that same notebook in the context of the OpenPathSampling official documentation. Note that these examples represent the most recent version of code, and may not be identical to what was included in the module. The original examples are included in the source code, below.