Command Line Interface

A separate command line tool for OpenPathSamplng can be installed. It is available via either conda or pip:

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

Once you install this, you’ll have access to the command openpathsampling in your shell (although we recommend aliasing that to either paths or ops – save yourself some typing!)

This command is a gateway to many subcommands, just like conda and pip (which have subcommands such as install) or git (which has subcommands such as clone or commit). You can get a full listing all the subcommands with openpathsampling --help. For more information on any given subcommand, use openpathsampling SUBCOMMAND --help, replacing SUBCOMMAND with the subcommand you’re interested in.

Here, we will provide a description of a few of the subcommands that the CLI tool provides. This documentation may not be fully up-to-date with the more recent releases of the CLI, so use the CLI help tools to get a fuller understanding of what is included.

For more details on how the CLI interprets its arguments, and to learn how to develop plugins for the CLI, see its documentation. The CLI subcommands are defined through a plugin system, which makes it very easy for developers to create new subcommands.

Workflow with the CLI

As always, the process of running a simulation is (1) set up the simulation; (2) run the simulation; (3) analyze the simulation. The CLI is mainly focused on step 2, although it also has tools that generally help with OPS files.

To use it, you’ll want to first set up your simulation, e.g., in a Jupyter notebook, and save the simulation objects to a storage file with storage.save(obj). You should tag you initial conditions with, e.g., storage.tags['initial_conditions'] = init_conds.

Close that storage file when you’re ready to run the simulation, and then you can run it with, e.g.,

openpathsampling pathsampling setup.nc -o output.nc --nsteps 1000

If the file you created, setup.nc has exactly one move scheme and has a sample set tagged as initial_conditions, the CLI will figure that out. Your output will be in output.nc, and you can analyze it in a Jupyter notebook, just as before.

Note that this can be especially useful when computing remotely. You can set up on your local machine, and then you just need to transfer the setup.nc to the remote machine (assuming you use internally-stored snapshots).

Finding your way around the CLI

Like many command line tools, the OPS CLI has the options -h or --help to get help. If you run openpathsampling --help you should see something like this

Usage: openpathsampling [OPTIONS] COMMAND [ARGS]...

  OpenPathSampling is a Python library for path sampling simulations. This
  command line tool facilitates common tasks when working with
  OpenPathSampling. To use it, use one of the subcommands below. For
  example, you can get more information about the pathsampling tool with:

      openpathsampling pathsampling --help

Options:
  --log PATH  logging configuration file
  -h, --help  Show this message and exit.

Simulation Commands:
  visit-all     Run MD to generate initial trajectories
  equilibrate   Run equilibration for path sampling
  pathsampling  Run any path sampling simulation, including TIS variants

Miscellaneous Commands:
  contents     list named objects from an OPS .nc file
  append       add objects from INPUT_FILE  to another file

The --log option takes a logging configuration file (e.g., logging.conf, and sets that logging behavior. If you use it, it must come before the subcommand name.

You can find out more about each subcommand by putting --help after the subcommand name, e.g., openpathsampling pathsampling --help, which returns

Usage: openpathsampling pathsampling [OPTIONS] INPUT_FILE

  General path sampling, using setup in INPUT_FILE

Options:
  -o, --output-file PATH  output ncfile  [required]
  -m, --scheme TEXT       identifier for the move scheme
  -t, --init-conds TEXT   identifier for initial conditions (sample set or
                          trajectory)
  -n, --nsteps INTEGER    number of Monte Carlo trials to run
  -h, --help              Show this message and exit.

Here you see the list of the options for the running a path sampling simulation. In general, path sampling requires an output file, a move scheme and initial conditions from some input file, and the number of steps to run. Note that only the output file is technically required: the CLI will default to running 0 steps (essentially, testing the validity of your setup), and it can try to guess the move scheme and initial conditions. In general, the way it guesses follows the following path:

  1. If there is only one object of the suitable type in the INPUT_FILE, use that.

  2. If there are multiple objects of the correct type, but only one has a name, use the named object.

  3. In special cases it looks for specific names, such as initial_conditions, and will use those.

Full details on how various CLI parameters search the storage can be seen in the Parameter Interpretation section of the CLI docs.

Simulation Commands

One of the main concepts when working with the CLI is that you can create all the OPS simulation objects without running the simulation, save them in an OPS storage file, and then load them again to actually run your simulation. For simulation commands, the options all deal with loading simulation objects from storage.

Here are some of the simulation commands implemented in the OPS CLI:

  • visit-all: create initial trajectories by running MD until all states have been visited (works for MSTIS or any 2-state system); must provide states, engine, and initial snapshot on command line

  • equilibrate: run equilibration for path sampling (until first decorrelated trajectory); must provide move scheme and initial conditions on the command line

  • pathsampling: run path sampling with a given move scheme (suitable for custom TPS schemes as well as TIS/RETIS); must provide move scheme, iniital conditions, and number of MC steps on command line

Miscellaneous Commands

Even for users who prefer to develop their OPS projects entirely in Python, foregoing the CLI tools to run simulations, some of the “miscellaneous” commands are likely to be quite useful. Here are some that are available in the CLI:

  • contents: list all the named objects in an OPS storage, organized by store (type); this is extremely useful to get the name of an object to use

  • append : add an object from once OPS storage into another one; this is useful for getting everything into a single file before running a simulation

Customizing the CLI

The OPS CLI uses a flexible plugin system to enable users to easily add custom functionality. This way, you can create and distribute custom plugins, giving more functionality to other users who would benefit from it, without adding everything to the core package and thus overwhelming new users.

Installing a plugin is easy: just create the directory $HOME/.openpathsampling/cli-plugins/, and copy the plugin Python script into there. For details on how to write a CLI plugin, see the CLI development docs.