OpenPathSampling CLI Core

This module provides the core infrastructure for the OpenPathSampling command line interface.

Purpose of Module

OpenPathSampling (OPS) is a powerful Python library for path sampling simulations. However, using it requires expertise in Python programming. In order to make OPS more accessible to a broader audience, we have begun development of a command line interface (CLI) to work with OPS files and to run OPS simulations.

The usage model is that there is a single command, openpathsampling, which takes subcommands and delegates them to different routines. This is the same model as, e.g., git, which has subcommands like git commit and git clone.

This module provides the underlying infrastructure/platform that the specific CLI subcommands will be built upon. A subsequent module will provide several specific subcommands.

Key functionality included here:

  • Parameter decorators: Different subcommands will frequently use the same options and arguments. In order to maintain consistency in parameter usage and help statements, common parameters have been implemented as a set of reusable decorators.
  • Plug-in infrastructure: To promote customizability, the OPS CLI uses a plug-in infrastructure. This allows us to ship a small set of default subcommands, but to allow users to easily create and share custom subcommands for their own projects or workflows. This module introduces two mechanisms by which a plug-in can register with the CLI. One is based on native namespace packages, which makes it easy for developers to create and distribute plug-ins that automatically register with OPS when installed with standard Python tools. The other approach is file-based, and simply involves placing the plug-in Python file in the user’s ~/.openpathsampling/cli-plugins/ directory. This approach is useful for quick development of plug-ins that may be intended to be shared within a specific research group or used to simplify reproducibility of workflows for a single project, but are not intended to be widely distributed and maintained for the long term.

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:

Detailed documentation on the CLI can be found at


The OPS CLI can be installed with either pip or conda:

pip install openpathsampling-cli
# or
conda install -c conda-forge openpathsampling-cli

Tests in the OpenPathSampling CLI use pytest. The requirements for testing are pytest and nose, both of which can also be installed with either pip or conda.

With the package and its testing tools installed, tests can be run with:

py.test --pyargs paths_cli


This module deals with the underlying platform on which the rest of the OPS CLI is built. As such, there are no direct examples. However, there are examples of how to use the platform, i.e., how to write plugins. Some of these can be found in the example_plugins directory. Additionally, the specific commands implemented for the OPS CLI 0.1, which will be the subject of a second module, can be thought of as examples.

Source Code

The source code for the OpenPathSampling CLI can be found in the its GitHub repository:

This module covers the “core” code for the OpenPathSampling CLI as of release version 0.1.

Specifically, it includes the following files, and their associated test suites: