From 489a25e89d1b74dba7cd048884bf33bbe71450cf Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@drexel.edu>
Date: Sat, 23 Oct 2010 08:38:04 -0400
Subject: [PATCH] Add epilogs to each OptionParser in pysawsim.

---
 pysawsim/histogram.py        |  3 ---
 pysawsim/parameter_scan.py   | 30 +++++++++++++++++++++++++-----
 pysawsim/sawsim.py           | 16 +++++++++++-----
 pysawsim/sawsim_histogram.py |  8 ++++++--
 4 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/pysawsim/histogram.py b/pysawsim/histogram.py
index ae8378a..34d47a6 100644
--- a/pysawsim/histogram.py
+++ b/pysawsim/histogram.py
@@ -79,9 +79,6 @@ class Histogram (object):
             <bin_edge><whitespace><count>
             ...
 
-        For example:
-
-
         `<bin_edge>` should mark the left-hand side of the bin, and
         all bins should be of equal width (so we know where the last
         one ends).
diff --git a/pysawsim/parameter_scan.py b/pysawsim/parameter_scan.py
index 60c60f9..03cd990 100644
--- a/pysawsim/parameter_scan.py
+++ b/pysawsim/parameter_scan.py
@@ -114,8 +114,8 @@ class HistogramMatcher (object):
 
     The input `histogram_stream` should contain a series of
     experimental histograms with '#HISTOGRAM: <params>` lines starting
-    each histogram.  `<params>` should list the `sawsim` parameters
-    that are unique to that experiment.
+    each histogram.  `<params>` lists the `sawsim` parameters that are
+    unique to that experiment.
 
     >>> from .manager.thread import ThreadManager
     >>> velocity_stream = StringIO(EXAMPLE_HISTOGRAM_FILE_CONTENTS)
@@ -326,9 +326,29 @@ def main(argv=None):
 
     sr = SawsimRunner()
 
-    usage = "%prog [options] velocity_file"
-
-    parser = OptionParser(usage)
+    usage = '%prog [options] histogram_file'
+    epilog = '\n'.join([
+            'Compare simulated results against experimental values over a',
+            'range of parameters.  Generates a plot of fit quality over',
+            'the parameter space.  The histogram file should look something',
+            'like:',
+            '',
+            EXAMPLE_HISTOGRAM_FILE_CONTENTS,
+            ''
+            '`#HISTOGRAM: <params>` lines start each histogram.  `params`',
+            'lists the `sawsim` parameters that are unique to that',
+            'experiment.',
+            '',
+            'Each histogram line is of the format:',
+            '',
+            '<bin_edge><whitespace><count>',
+            '',
+            '`<bin_edge>` should mark the left-hand side of the bin, and',
+            'all bins should be of equal width (so we know where the last',
+            'one ends).',
+            ])
+    parser = OptionParser(usage, epilog=epilog)
+    parser.format_epilog = lambda formatter: epilog+'\n'
     for option in sr.optparse_options:
         if option.dest == 'param_string':
             continue
diff --git a/pysawsim/sawsim.py b/pysawsim/sawsim.py
index 1500a93..858db1c 100644
--- a/pysawsim/sawsim.py
+++ b/pysawsim/sawsim.py
@@ -29,6 +29,7 @@ import hashlib
 from optparse import Option
 import os
 import os.path
+from random import shuffle
 import shutil
 from uuid import uuid4
 
@@ -36,7 +37,7 @@ from .manager import MANAGERS, get_manager, InvokeJob
 
 
 SAWSIM = 'sawsim'  # os.path.expand(os.path.join('~', 'bin', 'sawsim'))
-CACHE_DIR = os.path.expanduser(os.path.join('~', '.sawsim_cache'))
+CACHE_DIR = os.path.expanduser(os.path.join('~', '.sawsim-cache'))
 DEFAULT_PARAM_STRING = (
     '-s cantilever,hooke,0.05 -N1 '
     '-s folded,null -N8 '
@@ -191,7 +192,7 @@ class SawsimRunner (object):
         """
         >>> s = SawsimRunner()
         >>> s._param_cache_dir(DEFAULT_PARAM_STRING)  # doctest: +ELLIPSIS
-        '/.../.sawsim_cache/...'
+        '/.../.sawsim-cache/...'
         """
         return os.path.join(
             self._cache_dir, hashlib.sha256(param_string).hexdigest())
@@ -204,7 +205,7 @@ class SawsimRunner (object):
 
     def _load_cached_data(self, param_string):
         pcd = self._param_cache_dir(param_string)
-        for filename in os.listdir(pcd):
+        for filename in shuffle(os.listdir(pcd)):
             if not filename.endswith('.dat'):
                 continue
             with open(os.path.join(pcd, filename), 'r') as f:
@@ -285,8 +286,13 @@ def main(argv=None):
 
     sr = SawsimRunner()
 
-    usage = "%prog [options]"
-    parser = OptionParser(usage)
+    usage = '%prog [options]'
+    epilog = '\n'.join([
+            'Python wrapper around `sawsim`.  Distribute `N` runs using',
+            'one of the possible job "managers".  Also supports caching',
+            'results to speed future runs.'
+            ])
+    parser = OptionParser(usage, epilog=epilog)
     for option in sr.optparse_options:
         parser.add_option(option)
     
diff --git a/pysawsim/sawsim_histogram.py b/pysawsim/sawsim_histogram.py
index 6ca2cb2..ef02ffe 100644
--- a/pysawsim/sawsim_histogram.py
+++ b/pysawsim/sawsim_histogram.py
@@ -61,8 +61,12 @@ def main(argv=None):
 
     sr = SawsimRunner()
 
-    usage = "%prog [options] velocity_file"
-    parser = OptionParser(usage)
+    usage = '%prog [options]'
+    epilog = '\n'.join([
+            'Generate an unfolding force histogram from a series of `sawsim`',
+	    'runs.',
+            ])
+    parser = OptionParser(usage, epilog=epilog)
     for option in sr.optparse_options:
         parser.add_option(option)
     parser.add_option("-w", "--bin-width", dest="bin_width",
-- 
2.26.2