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:
- OPS documentation: http://openpathsampling.org
- OPS source code: http://github.com/openpathsampling/openpathsampling
Detailed documentation on the CLI can be found at https://openpathsampling-cli.readthedocs.io/
Testing¶
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
Examples¶
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: http://github.com/openpathsampling/openpathsampling-cli.
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:
cli.pyparam_core.pyparameters.pyplugin_management.py