Merge pull request #21 from openpathsampling/release-0.0.3

Release 0.0.3

Author: dwhswenson

README.md

@@ -28,7 +28,6 @@ miscellaneous operations on OPS output files.
 **Miscellaneous Commands:**
 
 * `contents`:         List named objects from an OPS .nc file
-* `strip-snapshots`:  Remove coordinates/velocities from an OPS storage
 * `append`:           add objects from INPUT_FILE  to another file
 
 Full documentation is at https://openpathsampling-cli.readthedocs.io/; a brief

devtools/miniconda_install.sh

@@ -22,7 +22,7 @@ conda_version="latest"
 #conda_version="4.4.10"  # can pin a miniconda version like this, if needed
 
 MINICONDA=Miniconda${pyV}-${conda_version}-${OS_ARCH}.sh
-MINICONDA_MD5=$(curl -s https://repo.continuum.io/miniconda/ | grep -A3 $MINICONDA | sed -n '4p' | sed -n 's/ *<td>\(.*\)<\/td> */\1/p')
+MINICONDA_MD5=$(curl -sL https://repo.continuum.io/miniconda/ | grep -A3 $MINICONDA | sed -n '4p' | sed -n 's/ *<td>\(.*\)<\/td> */\1/p')
 wget https://repo.continuum.io/miniconda/$MINICONDA
 SCRIPT_MD5=`eval "$MD5_CMD $MD5_OPT $MINICONDA" | cut -d ' ' -f 1`
 

docs/for_core/cli.rst

@@ -28,8 +28,8 @@ 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.
 
-* CLI documentation:
-* CLI code repository:
+* CLI documentation: https://openpathsampling-cli.readthedocs.io/
+* CLI code repository: https://github.com/openpathsampling/openpathsampling-cli/
 
 Workflow with the CLI
 ---------------------
@@ -41,6 +41,76 @@ files.
 
 To use it, you'll want to first set up 
 
+
+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
+<https://openpathsampling-cli.readthedocs.io/en/latest/interpretation.html>`_
+section of the CLI docs.
+
 Simulation Commands
 -------------------
 
@@ -68,9 +138,6 @@ Here are some of the simulation commands implemented in the OPS CLI:
   have been visited (works for MSTIS or any 2-state system); must provide
   states, engine, and initial snapshot on command line
 
-.. TODO figure showing how these all work -- what is needed for each, what
-   is implicit
-
 Miscellaneous Commands
 ----------------------
 
@@ -79,10 +146,29 @@ 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:
 
-* ``nclist``: list all the named objects in an OPS storage, organized by
+* ``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
-  as command-line input to one of the simulation scripts
-* ``strip-snapshots``: create a copy of the input storage file with the
+
+
+.. * ``strip-snapshots``: create a copy of the input storage file with the
   details (coordinates/velocities) of all snapshots removed; this allows you
   to make a much smaller copy (with results of CVs) to copy back to a local
   computer for analysis
+
+* ``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 <https://openpathsampling-cli.readthedocs.io/>`_.

docs/full_cli.rst

@@ -9,6 +9,6 @@ currently gives all commands alphabetically, without regard to section. In
 general, this is not yet well-organized; contributions to improve that would
 be appreciated.
 
-.. click:: paths_cli.cli:OPS_CLI
+.. click:: paths_cli.cli:main
    :prog: openpathsampling
    :show-nested:

docs/sphinx-helpers/make_param_table.py

@@ -12,6 +12,7 @@
 import click
 
 from paths_cli import parameters
+from  paths_cli import param_core
 
 TableEntry = collections.namedtuple("TableEntry",
                                     "param flags get_args help")
@@ -20,7 +21,7 @@ def is_click_decorator(thing):
     return getattr(thing, '__module__', None) == 'click.decorators'
 
 def is_parameter(thing):
-    return (isinstance(thing, parameters.AbstractLoader)
+    return (isinstance(thing, param_core.AbstractLoader)
             or is_click_decorator(thing))
 
 def rst_wrap(code):
@@ -33,18 +34,18 @@ def flags_help(click_decorator):
     return flags, help_
 
 def get_args(parameter):
-    if isinstance(parameter, parameters.StorageLoader):
+    if isinstance(parameter, param_core.StorageLoader):
         return "``name``"
-    elif isinstance(parameter, (parameters.OPSStorageLoadNames,
-                                parameters.OPSStorageLoadSingle)):
+    elif isinstance(parameter, (param_core.OPSStorageLoadNames,
+                                param_core.OPSStorageLoadSingle)):
         return "``storage``, ``name``"
     elif is_click_decorator(parameter):
         return "No ``get`` function"
     else:
         return "Unknown"
 
 def get_click_decorator(thing):
-    if isinstance(thing, parameters.AbstractLoader):
+    if isinstance(thing, param_core.AbstractLoader):
         return thing.param.clicked()
     elif is_click_decorator(thing):
         return thing

paths_cli/cli.py

@@ -4,6 +4,8 @@
 """
 # builds off the example of MultiCommand in click's docs
 import collections
+import logging
+import logging.config
 import os
 
 import click
@@ -36,16 +38,30 @@ def __init__(self, *args, **kwargs):
                 self.plugin_folders.append(folder)
 
         plugin_files = self._list_plugin_files(self.plugin_folders)
-        self.plugins = self._load_plugin_files(plugin_files)
+        plugins = self._load_plugin_files(plugin_files)
 
         self._get_command = {}
         self._sections = collections.defaultdict(list)
-        for plugin in self.plugins:
-            self._get_command[plugin.name] = plugin.func
-            self._sections[plugin.section].append(plugin.name)
+        self.plugins = []
+        for plugin in plugins:
+            self._register_plugin(plugin)
 
         super(OpenPathSamplingCLI, self).__init__(*args, **kwargs)
 
+    def _register_plugin(self, plugin):
+        self.plugins.append(plugin)
+        self._get_command[plugin.name] = plugin.func
+        self._sections[plugin.section].append(plugin.name)
+
+    def _deregister_plugin(self, plugin):
+        # mainly used in testing
+        self.plugins.remove(plugin)
+        del self._get_command[plugin.name]
+        self._sections[plugin.section].remove(plugin.name)
+
+    def plugin_for_command(self, command_name):
+        return {p.name: p for p in self.plugins}[command_name]
+
     @staticmethod
     def _list_plugin_files(plugin_folders):
         def is_plugin(filename):
@@ -112,22 +128,22 @@ def format_commands(self, ctx, formatter):
 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 strip-snapshots (filesize reduction)
-tool with:
+you can get more information about the pathsampling tool with:
 
-    openpathsampling strip-snapshots --help
+    openpathsampling pathsampling --help
 """
 
-OPS_CLI = OpenPathSamplingCLI(
-    name="openpathsampling",
-    help=_MAIN_HELP,
-    context_settings=CONTEXT_SETTINGS
-)
-
-def main():  # no-cov
-    OPS_CLI()
+@click.command(cls=OpenPathSamplingCLI, name="openpathsampling",
+               help=_MAIN_HELP, context_settings=CONTEXT_SETTINGS)
+@click.option('--log', type=click.Path(exists=True, readable=True),
+              help="logging configuration file")
+def main(log):
+    if log:
+        logging.config.fileConfig(log, disable_existing_loggers=False)
+    # TODO: if log not given, check for logging.conf in .openpathsampling/
 
+    logger = logging.getLogger(__name__)
+    logger.debug("About to run command")  # TODO: maybe log invocation?
 
 if __name__ == '__main__':  # no-cov
     main()
-    # print("list commands:", cli.list_commands())