Merge pull request #69 from Becksteinlab/automatic-tool-loading

* Tries to detect and load GMXRC automatically (PR #55)
* automatic environment settings from GMXRC (#55)
* load Gromacs tools automatically if they can be seen in the environment (closes #68)

.gitignore

@@ -6,6 +6,8 @@ doc/epydoc/
 doc/sphinx/build/
 doc/html
 build/
+.idea/
+virtualenv/
 dist
 gromacs.log
 doc/sphinx/*.log

CHANGES

@@ -10,6 +10,8 @@ pslacerda, orbeckst
   automatically before setting up the Gromacs commands (#55)
 * doc strings for Gromacs tools are loaded lazily, which speeds up
   the initial import of the library to almost instantaneously (PR #76)
+* guess which tools to load automatically if no tools option is provided (#68)
+* new documentation page on how to set up a cfg file
 
 2016-06-29      0.5.1
 whitead, dotsdl, orbeckst

doc/sphinx/source/configuration.txt

@@ -0,0 +1,123 @@
+==============
+ Configuration
+==============
+
+.. highlight:: ini
+
+This section documents how to configure the **GromacsWrapper** package. There
+are options to configure where log files and templates directories are located
+and options to tell exactly which commands to load into this package. Any
+configuration is optional and all options has sane defaults. Further
+documentation can be found at :mod:`gromacs.config`.
+
+.. versionchanged:: 0.6.0
+   The format of the ``tools`` variable in the ``[Gromacs]`` section of the
+   config file was changed for Gromacs 5 commands.
+
+Basic options
+-------------
+
+Place an INI file named ``~/.gromacswrapper.cfg`` in your home directory, it
+may look like the following document::
+
+  [Gromacs]
+  GMXRC = /usr/local/gromacs/bin/GMXRC
+
+The Gromacs software suite needs some environment variables that are set up
+sourcing the ``GMXRC`` file. You may source it yourself or set an option like
+the above one. If this option isn't provided, **GromacsWrapper** will guess
+that Gromacs was globally installed like if it was installed by the ``apt-get``
+program.
+
+As there isn't yet any way to know which Gromacs version to use,
+**GromacsWrapper** will first try to use Gromacs 5 if available, then to use
+Gromacs 4. If you have both versions and want to use version 4 or just want
+to document it, you may specify the which release version will be used::
+
+  [Gromacs]
+  GMXRC = /usr/local/gromacs/bin/GMXRC
+  release = 4.6.7
+
+For now **GromacsWrapper** will guess which tools are available to put it into
+:mod:`gromacs.tools`, but you can always configure it manually. Gromacs 5 has
+up to 4 commands usually named::
+
+  [Gromacs]
+  tools = gmx gmx_d gmx_mpi gmx_mpi_d
+
+
+This option will instruct which commands to load. For Gromacs 4 you'll need to
+specify more tools::
+
+  [Gromacs]
+  GMXRC = /usr/local/gromacs/bin/GMXRC
+  release = 4
+  tools =
+	           g_cluster     g_dyndom       g_mdmat      g_principal  g_select    g_wham    mdrun
+	do_dssp    g_clustsize   g_enemat       g_membed     g_protonate  g_sgangle   g_wheel   mdrun_d
+	editconf   g_confrms     g_energy       g_mindist    g_rama       g_sham      g_x2top   mk_angndx
+	eneconv    g_covar       g_filter       g_morph      g_rdf        g_sigeps    genbox    pdb2gmx
+	g_anadock  g_current     g_gyrate       g_msd                     g_sorient   genconf
+	g_anaeig   g_density     g_h2order      g_nmeig      g_rms        g_spatial   genion    tpbconv
+	g_analyze  g_densmap     g_hbond        g_nmens      g_rmsdist    g_spol      genrestr  trjcat
+	g_angle    g_dielectric  g_helix        g_nmtraj     g_rmsf       g_tcaf      gmxcheck  trjconv
+	g_bar      g_dih         g_helixorient  g_order      g_rotacf     g_traj      gmxdump   trjorder
+	g_bond     g_dipoles     g_kinetics     g_pme_error  g_rotmat     g_tune_pme  grompp
+	g_bundle   g_disre       g_lie          g_polystat   g_saltbr     g_vanhove   make_edi  xpm2ps
+	g_chi      g_dist        g_luck         g_potential  g_sas        g_velacc    make_ndx
+
+
+Commands will be available directly from the :mod:`gromacs`:
+
+.. code-block:: python
+
+    import gromacs
+    gromacs.mdrun_d # either v5 `gmx_d mdrun` or v4 `mdrun_d`
+    gromacs.mdrun   # either v5 `gmx mdrun`   or v4 `mdrun`
+
+
+More options
+------------
+
+Other options are to set where template for job submission systems and.mdp
+files are located::
+
+  [DEFAULT]
+  # Directory to store user templates and rc files.
+  configdir = ~/.gromacswrapper
+
+  # Directory to store user supplied queuing system scripts.
+  qscriptdir = %(configdir)s/qscripts
+
+  # Directory to store user supplied template files such as mdp files.
+  templatesdir = %(configdir)s/templates
+
+  # Directory to store manager configuration files
+  managerdir = %(configdir)s/managers
+
+
+And there are yet options for how to handle logging::
+
+  [Logging]
+  # name of the logfile that is written to the current directory
+  logfilename = gromacs.log
+
+  # loglevels (see Python's logging module for details)
+  #   ERROR   only fatal errors
+  #   WARN    only warnings
+  #   INFO    interesting messages
+  #   DEBUG   everything
+
+  # console messages written to screen
+  loglevel_console = INFO
+
+  # file messages written to logfilename
+  loglevel_file = DEBUG
+
+If needed you may set up basic configuration files and directories using
+:func:`gromacs.config.setup`:
+
+.. code-block:: python
+
+  import gromacs
+  gromacs.config.setup()

doc/sphinx/source/index.txt

@@ -57,6 +57,7 @@ Contents
    :maxdepth: 2
 
    installation
+   configuration
    gromacs
    analysis
    auxiliary

gromacs/__init__.py

@@ -3,8 +3,7 @@
 # Released under the GNU Public License 3 (or higher, your choice)
 # See the file COPYING for details.
 
-"""
-:mod:`gromacs` -- GromacsWrapper Package Overview
+""":mod:`gromacs` -- GromacsWrapper Package Overview
 =================================================
 
 **GromacsWrapper** (package :mod:`gromacs`) is a thin shell around the `Gromacs`_
@@ -160,6 +159,11 @@
 instead of displaying it on screen, as described under
 :ref:`input-output-label`.
 
+Normally, one starts logging with the :func:`start_logging` function but in
+order to obtain logging messages (typically at level *debug*) right from the
+start one may set the environment variable :envvar:`GW_START_LOGGING` to any
+value that evaluates to ``True`` (e.g., "True" or "1").
+
 .. _logging: http://docs.python.org/library/logging.html
 
 Version
@@ -173,10 +177,13 @@
 If the package was installed from a development version, the patch
 level will have the string "-dev" affixed to distinguish it from a
 release.
+
 """
 from __future__ import absolute_import
 __docformat__ = "restructuredtext en"
 
+import os
+
 from .version import VERSION, RELEASE, get_version, get_version_tuple
 
 # __all__ is extended with all gromacs command instances later
@@ -240,6 +247,9 @@ def stop_logging():
     logger.info("GromacsWrapper %s STOPPED logging", get_version())
     log.clear_handlers(logger)  # this _should_ do the job...
 
+# for testing (maybe enable with envar GW_START_LOGGING)
+if os.environ.get('GW_START_LOGGING', False):
+    start_logging()
 
 # Try to load environment variables set by GMXRC
 config.set_gmxrc_environment(config.cfg.getpath("Gromacs", "GMXRC"))

gromacs/cbook.py

@@ -199,7 +199,7 @@ def _define_canned_commands():
 
 try:
     _define_canned_commands()
-except (OSError, ImportError, GromacsError):
+except (OSError, ImportError, AttributeError, GromacsError):
     msg = ("Failed to define a number of commands in gromacs.cbook. Most "
           "likely the Gromacs installation cannot be found --- set GMXRC in "
            "~/.gromacswrapper.cfg or source GMXRC directly")
@@ -1652,7 +1652,7 @@ class Transformer(utilities.FileUtils):
 
     """
 
-    def __init__(self, s="topol.tpr", f="traj.xtc", n=None, force=None, 
+    def __init__(self, s="topol.tpr", f="traj.xtc", n=None, force=None,
                  dirname=os.path.curdir, outdir=None):
         """Set up Transformer with structure and trajectory.
 
@@ -1732,7 +1732,7 @@ def center_fit(self, **kwargs):
         """Write compact xtc that is fitted to the tpr reference structure.
 
         See :func:`gromacs.cbook.trj_fitandcenter` for details and
-        description of *kwargs* (including *input*, *input1*, *n* and 
+        description of *kwargs* (including *input*, *input1*, *n* and
         *n1* for how to supply custom index groups). The most important ones are listed
         here but in most cases the defaults should work.
 
@@ -1846,7 +1846,7 @@ def fit(self, xy=False, **kwargs):
                 logger.info("Fitted trajectory (fitmode=%s): %r.", fitmode, kwargs['o'])
         return {'tpr': self.rp(kwargs['s']), 'xtc': self.rp(kwargs['o'])}
 
-    def strip_water(self, os=None, o=None, on=None, compact=False, 
+    def strip_water(self, os=None, o=None, on=None, compact=False,
                     resn="SOL", groupname="notwater", **kwargs):
         """Write xtc and tpr with water (by resname) removed.
 
@@ -1866,7 +1866,7 @@ def strip_water(self, os=None, o=None, on=None, compact=False,
               Index group used for centering ["Protein"]
 
               .. Note:: If *input* is provided (see below under *kwargs*)
-                        then *centergroup* is ignored and the group for 
+                        then *centergroup* is ignored and the group for
                         centering is taken as the first entry in *input*.
 
            *resn*
@@ -1909,12 +1909,12 @@ def strip_water(self, os=None, o=None, on=None, compact=False,
             TRJCONV = trj_compact
             # input overrides centergroup
             if kwargs.get('centergroup') is not None and 'input' in kwargs:
-		logger.warn("centergroup = %r will be superceded by input[0] = %r", kwargs['centergroup'], kwargs['input'][0])
+                logger.warn("centergroup = %r will be superceded by input[0] = %r", kwargs['centergroup'], kwargs['input'][0])
             _input = kwargs.get('input', [kwargs.get('centergroup', 'Protein')])
             kwargs['input'] = [_input[0], groupname]  # [center group, write-out selection]
             del _input
-	    logger.info("Creating a compact trajectory centered on group %r", kwargs['input'][0])
-	    logger.info("Writing %r to the output trajectory", kwargs['input'][1])
+            logger.info("Creating a compact trajectory centered on group %r", kwargs['input'][0])
+            logger.info("Writing %r to the output trajectory", kwargs['input'][1])
         else:
             TRJCONV = gromacs.trjconv
             kwargs['input'] = [groupname]
@@ -1937,7 +1937,7 @@ def strip_water(self, os=None, o=None, on=None, compact=False,
 
                 logger.info("NDX of the new system %r", newndx)
                 gromacs.make_ndx(f=newtpr, o=newndx, input=['q'], stderr=False, stdout=False)
-		# PROBLEM: If self.ndx contained a custom group required for fitting then we are loosing
+                # PROBLEM: If self.ndx contained a custom group required for fitting then we are loosing
                 #          this group here. We could try to merge only this group but it is possible that
                 #          atom indices changed. The only way to solve this is to regenerate the group with
                 #          a selection or only use Gromacs default groups.
@@ -2083,7 +2083,7 @@ def strip_fit(self, **kwargs):
         - *fitgroup* is only passed to :meth:`fit` and just contains
           the group to fit to ("backbone" by default)
 
-	  .. warning:: *fitgroup* can only be a Gromacs default group and not
+          .. warning:: *fitgroup* can only be a Gromacs default group and not
                        a custom group (because the indices change after stripping)
 
         - By default *fit* = "rot+trans" (and *fit* is passed to :meth:`fit`,