Package gromacs :: Module config

Module config


:mod:`gromacs.config` -- Configuration for GromacsWrapper
==========================================================

The config module provides configurable options for the whole package;
eventually it might grow into a sophisticated configuration system such as
matplotlib's rc system but right now it mostly serves to define which gromacs
tools and other scripts are offered in the package and where template files are
located. If the user wants to change anything they will still have to do it
here in source until a better mechanism with rc files has been implemented.

User-supplied templates are stored under
:data:`gromacs.config.configdir`. Eventually this will also contain the
configuration options currently hard-coded in :mod:`gromacs.config`.

.. autodata:: configdir
.. autodata:: path

The user should execute :func:`gromacs.config.setup` at least once to
prepare the user configurable area in their home directory::

  import gromacs
  gromacs.config.setup()


Logging
-------

Gromacs commands log their invocation to a log file; typically at
loglevel *INFO* (see the python `logging module`_ for details).

.. autodata:: logfilename
.. autodata:: loglevel_console
.. autodata:: loglevel_file

.. _logging module: http://docs.python.org/library/logging.html


Gromacs tools and scripts
-------------------------

``load_*`` variables are lists that contain instructions to other
parts of the code which packages and scripts should be wrapped.

.. autodata:: load_tools
.. autodata:: load_scripts

:data:`load_tools` is populated by listing ``gmx_*`` tool group variables in
:data:`gmx_tool_groups`. 

.. autodata:: gmx_tool_groups

The tool groups variables are strings that contain white-space separated file
names of Gromacs tools. These lists determine which tools are made available as
classes in :mod:`gromacs.tools`.

.. autodata:: gmx_tools
.. autodata:: gmx_extra_tools


Location of template files
--------------------------

*Template variables* list files in the package that can be used as
templates such as run input files. Because the package can be a zipped
egg we actually have to unwrap these files at this stage but this is
completely transparent to the user.

.. autodata:: qscriptdir
.. autodata:: templatesdir
.. autodata:: templates
.. autodata:: qscript_template
.. autofunction:: setup

Accessing configuration data
----------------------------

The following functions can be used to access configuration data. Note that
files are searched first with their full filename, then in all directories
listed in :data:`gromacs.config.path`, and finally within the package itself.

.. autofunction:: get_template
.. autofunction:: get_templates

Functions

[hide private]

setup()
Create the directories in which the user can store template and config files.

source code

check_setup()
Check if templates directories are setup and issue a warning and help.

source code

_generate_template_dict(dirname)
Generate a list of included files *and* extract them to a temp space.

source code

resource_basename(resource)
Last component of a resource (which always uses '/' as sep).

source code

get_template(t)
Find template file *t* and return its real path.

source code

get_templates(t)
Find template file(s) *t* and return their real paths.

source code

_get_template(t)
Return a single template *t*.

source code

Variables

[hide private]

logfilename = 'gromacs.log'
File name for the log file; all gromacs command and many utility functions (e.g.

loglevel_console = 20
The default loglevel that is still printed to the console.

loglevel_file = 10
The default loglevel that is still written to the :data:`logfilename`.

configdir = '/sansom/gfio/users/oliver/.gromacswrapper'
Directory to store user templates and rc files.

qscriptdir = '/sansom/gfio/users/oliver/.gromacswrapper/qscripts'
Directory to store user supplied queuing system scripts.

templatesdir = '/sansom/gfio/users/oliver/.gromacswrapper/templates'
Directory to store user supplied template files such as mdp files.

path = ['.', '/sansom/gfio/users/oliver/.gromacswrapper/qscripts', '...
Search path for user queuing scripts and templates.

gmx_tool_groups = ['gmx_tools', 'gmx_extra_tools']
List of the variables in gromacs.tools that should be loaded.

gmx_tools = 'anadock g_current g_helix g_rama ...
Contains the file names of all Gromacs tools for which classes are generated.

gmx_tools_402 = 'anadock g_current g_helix g_r...

gmx_extra_tools = 'g_count g_flux g_zcoord\ng_ri3D...
Additional gromacs tools (add *gmx_extra_tools* to :data:`gromacs.config.gmx_tool_groups` to enable them, provided the binaries have been provided on the :envvar:`PATH`).

load_tools = ['anadock', 'g_current', 'g_helix', 'g_rama', 'g_...
Python list of all tool file names.

GridMAT_MD = '/sansom/gfio/users/oliver/Library/python/GromacsWrappe...

load_scripts = [('/sansom/gfio/users/oliver/Library/python/GromacsWr...
3rd party analysis scripts and tools; this is a list of triplets of

templates = {'.#md_OPLSAA.mdp': '/sansom/gfio/users/oliver/Library/p...
*GromacsWrapper* comes with a number of templates for run input files and queuing system scripts.

qscript_template = '/sansom/gfio/users/oliver/Library/python/Gromacs...
The default template for SGE/PBS run scripts.

Function Details

[hide private]

setup()

source code

Create the directories in which the user can store template and config files.

This function can be run repeatedly without harm.

_generate_template_dict(dirname)

source code

Generate a list of included files *and* extract them to a temp space.

Templates have to be extracted from the egg because they are used by external code. All template filenames are stored in :data:`config.templates`.

get_template(t)

source code

Find template file *t* and return its real path.

*t* can be a single string or a list of strings. A string
should be one of

1. a relative or absolute path,
2. a file in one of the directories listed in :data:`gromacs.config.path`,
3. a filename in the package template directory (defined in the template dictionary
   :data:`gromacs.config.templates`) or
4. a key into :data:`~gromacs.config.templates`.

The first match (in this order) is returned. If the argument is a
single string then a single string is returned, otherwise a list
of strings.

:Arguments: *t* : template file or key (string or list of strings)
:Returns:   os.path.realpath(*t*) (or a list thereof)
:Raises:    :exc:`ValueError` if no file can be located.

get_templates(t)

source code

Find template file(s) *t* and return their real paths.

*t* can be a single string or a list of strings. A string should
be one of

1. a relative or absolute path,
2. a file in one of the directories listed in :data:`gromacs.config.path`,
3. a filename in the package template directory (defined in the template dictionary
   :data:`gromacs.config.templates`) or
4. a key into :data:`~gromacs.config.templates`.

The first match (in this order) is returned for each input argument.

:Arguments: *t* : template file or key (string or list of strings)
:Returns:   list of os.path.realpath(*t*) 
:Raises:    :exc:`ValueError` if no file can be located.

Variables Details

[hide private]

logfilename

File name for the log file; all gromacs command and many utility functions (e.g. in :mod:`gromacs.cbook` and :mod:`gromacs.setup`) append messages there. Warnings and errors are also recorded here. The default is *gromacs.log*.

Value:

'gromacs.log'

configdir

Directory to store user templates and rc files. The default value is ``~/.gromacswrapper``.

Value:

'/sansom/gfio/users/oliver/.gromacswrapper'

qscriptdir

Directory to store user supplied queuing system scripts. The default value is ``~/.gromacswrapper/qscripts``.

Value:

'/sansom/gfio/users/oliver/.gromacswrapper/qscripts'

templatesdir

Directory to store user supplied template files such as mdp files. The default value is ``~/.gromacswrapper/templates``.

Value:

'/sansom/gfio/users/oliver/.gromacswrapper/templates'

path

Search path for user queuing scripts and templates. The internal package-supplied templates are always searched last via :func:`gromacs.config.get_templates`. Modify :data:`gromacs.config.path` directly in order to customize the template and qscript searching. By default it has the value ``['.', qscriptdir, templatesdir]``. (Note that it is not a good idea to have template files and qscripts with the same name as they are both searched on the same path.)

Value:

['.',
 '/sansom/gfio/users/oliver/.gromacswrapper/qscripts',
 '/sansom/gfio/users/oliver/.gromacswrapper/templates']

gmx_tool_groups

List of the variables in gromacs.tools that should be loaded. Possible values: *gmx_tools*, *gmx_extra_tools*. Right now these are variable names in :mod:`gromacs.config`, referencing :data:`gromacs.config.gmx_tools` and :data:`gromacs.config.gmx_extra_tools`.

Value:

['gmx_tools', 'gmx_extra_tools']

gmx_tools

Contains the file names of all Gromacs tools for which classes are generated. Editing this list has only an effect when the package is reloaded. If you want additional tools then add the, to the source (``config.py``) or derive new classes manually from :class:`gromacs.core.GromacsCommand`. (Eventually, this functionality will be in a per-user configurable file.) The current list was generated from Gromacs 4.0.99 (git). Removed (because of various issues)

g_kinetics

Value:

'''anadock      g_current     g_helix        g_rama     g_traj     mdr
un_d
             g_density     g_helixorient  g_rdf      g_vanhove  mk_ang
ndx
do_dssp      g_densmap                    g_rms      g_velacc   pdb2gm
x
editconf     g_dielectric  g_lie                     g_wham     proton
ate
...

gmx_tools_402

Value:

'''anadock      g_current     g_helix        g_rama     g_traj     mdr
un_d
demux.pl     g_density     g_helixorient  g_rdf      g_vanhove  mk_ang
ndx
do_dssp      g_densmap     g_kinetics     g_rms      g_velacc   pdb2gm
x
editconf     g_dielectric  g_lie          g_rmsdist  g_wham     proton
ate
...

gmx_extra_tools

Additional gromacs tools (add *gmx_extra_tools* to :data:`gromacs.config.gmx_tool_groups` to enable them, provided the binaries have been provided on the :envvar:`PATH`).

Value:

'''g_count      g_flux        g_zcoord
g_ri3Dc      a_ri3Dc       a_gridcalc
'''

load_tools

Python list of all tool file names. Automatically filled from :data:`gmx_tools` and :data:`gmx_extra_tools`, depending on the values in :data:`gmx_tool_groups`.

Value:

['anadock',
 'g_current',
 'g_helix',
 'g_rama',
 'g_traj',
 'mdrun_d',
 'g_density',
 'g_helixorient',
...

GridMAT_MD

Value:

'/sansom/gfio/users/oliver/Library/python/GromacsWrapper/gromacs/external/Gr
idMAT-MD_v1.0.2/GridMAT-MD.pl'

load_scripts

3rd party analysis scripts and tools; this is a list of triplets of

  (*script name/path*, *command name*, *doc string*)

(See the source code for examples.)

Value:

[('/sansom/gfio/users/oliver/Library/python/GromacsWrapper/gromacs/external/
GridMAT-MD_v1.0.2/GridMAT-MD.pl',
  'GridMAT_MD',
  '''GridMAT-MD: A Grid-based Membrane Analysis Tool for use with Mole
cular Dynamics.

*This* ``GridMAT-MD`` is a patched version of the original
``GridMAT-MD.pl`` v1.0.2, written by WJ Allen, JA Lemkul and DR
...

templates

*GromacsWrapper* comes with a number of templates for run input files
and queuing system scripts. They are provided as a convenience and
examples but **WITHOUT ANY GUARANTEE FOR CORRECTNESS OR SUITABILITY FOR
ANY PURPOSE**.

All template filenames are stored in
:data:`gromacs.config.templates`. Templates have to be extracted from
the GromacsWrapper python egg file because they are used by external
code: find the actual file locations from this variable.

**Gromacs mdp templates**

   These are supplied as examples and there is **NO GUARANTEE THAT THEY
   PRODUCE SENSIBLE OUTPUT** --- check for yourself!  Note that only
   existing parameter names can be modified with
   :func:`gromacs.cbook.edit_mdp` at the moment; if in doubt add the
   parameter with its gromacs default value (or empty values) and
   modify later with :func:`~gromacs.cbook.edit_mdp`.

   The safest bet is to use one of the ``mdout.mdp`` files produced by
   :func:`gromacs.grompp` as a template as this mdp contains all
   parameters that are legal in the current version of Gromacs.

**Queuing system templates**

   The queing system scripts are highly specific and you will need to add your
   own into :data:`gromacs.config.qscriptdir`. 
   See :mod:`gromacs.qsub` for the format and how these files are processed.

Value:

{'.#md_OPLSAA.mdp': '/sansom/gfio/users/oliver/Library/python/GromacsWrapper
/gromacs/templates/.#md_OPLSAA.mdp',
 'astrocyte.sge': '/sansom/gfio/users/oliver/Library/python/GromacsWrapper/g
romacs/templates/astrocyte.sge',
 'darwin.sh': '/sansom/gfio/users/oliver/Library/python/GromacsWrapper/groma
cs/templates/darwin.sh',
 'deathspud.sge': '/sansom/gfio/users/oliver/Library/python/GromacsWrapper/g
romacs/templates/deathspud.sge',
...

qscript_template

The default template for SGE/PBS run scripts.

Value:

'/sansom/gfio/users/oliver/Library/python/GromacsWrapper/gromacs/templates/l
ocal.sh'