gromacs.config – Configuration for GromacsWrapper — GromacsWrapper 0.6.1 documentation

# `gromacs.config` – Configuration for GromacsWrapper

The config module provides configurable options for the whole package; It serves to define how to handle log files, set where template files are located and which gromacs tools are exposed in the `gromacs` package.

In order to set up a basic configuration file and the directories a user can execute `gromacs.config.setup()`.

If the configuration file is edited then one can force a rereading of the new config file with `gromacs.config.get_configuration()`:

    gromacs.config.get_configuration()

However, this will not update the available command classes (e.g. when new executables were added to a tool group). In this case one either has to `reload()` a number of modules (`gromacs`, `gromacs.config`, `gromacs.tools`) although it is by far easier simply to quit python and freshly `import gromacs`.

Almost all aspects of GromacsWrapper (paths, names, what is loaded) can be changed from within the configuration file. The only exception is the name of the configuration file itself: This is hard-coded as `~/.gromacswrapper.cfg` although it is possible to read other configuration files with the filename argument to `get_configuration()`.

## Configuration management

Important configuration variables are

`gromacs.config.` `configdir` = '/Users/oliver/.gromacswrapper'

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

`gromacs.config.` `path` = ['.', '/Users/oliver/.gromacswrapper/qscripts', '/Users/oliver/.gromacswrapper/templates']

  Search path for user queuing scripts and templates. The internal package-supplied templates are always searched last via `gromacs.config.get_templates()`. Modify `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.) `path` is updated whenever cfg is re-read with `get_configuration()`.

When GromacsWrapper starts up it runs `check_setup()`. This notifies the user if any config files or directories are missing and suggests to run `setup()`. The check if the default set up exists can be suppressed by setting the environment variable `GROMACSWRAPPER_SUPPRESS_SETUP_CHECK` to ‘true’ (‘yes’ and ‘1’ also work).

### Users

Users will likely only need to run `gromacs.config.setup()` once and perhaps occasionally execute `gromacs.config.get_configuration()`. Mainly the user is expected to configure GromacsWrapper by editing the configuration file `~/.gromacswrapper.cfg` (which has ini-file syntax as described in `ConfigParser`).

`gromacs.config.` `setup`(filename='/Users/oliver/.gromacswrapper.cfg')

  Prepare a default GromacsWrapper global environment.

  1. Create the global config file.
  2. Create the directories in which the user can store template and config files.

  This function can be run repeatedly without harm.

`gromacs.config.` `get_configuration`(filename='/Users/oliver/.gromacswrapper.cfg')

  Reads and parses the configuration file.

  Default values are loaded and then replaced with the values from `~/.gromacswrapper.cfg` if that file exists. The global configuration instance `gromacswrapper.config.cfg` is updated as are a number of global variables such as `configdir`, `qscriptdir`, `templatesdir`, `logfilename`, ...

  Normally, the configuration is only loaded when the `gromacs` package is imported but a re-reading of the configuration can be forced anytime by calling `get_configuration()`.

  Returns: | a dict with all updated global configuration variables

`gromacs.config.` `check_setup`()

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

  Set the environment variable `GROMACSWRAPPER_SUPPRESS_SETUP_CHECK` skip the check and make it always return `True`

  :return `True` if directories were found and `False` otherwise

  > Changed in version 0.3.1: Uses `GROMACSWRAPPER_SUPPRESS_SETUP_CHECK` to suppress check (useful for scripts run on a server)

### Developers

Developers are able to access all configuration data through `gromacs.config.cfg`, which represents the merger of the package default values and the user configuration file values.

`gromacs.config.` `cfg` = <gromacs.config.GMXConfigParser instance>

  `cfg` is the instance of `GMXConfigParser` that makes all global configuration data accessible

class `gromacs.config.` `GMXConfigParser`(*args, **kwargs)

  Customized `ConfigParser.SafeConfigParser`.

  Reads and parses the configuration file.

  Default values are loaded and then replaced with the values from `~/.gromacswrapper.cfg` if that file exists. The global configuration instance `gromacswrapper.config.cfg` is updated as are a number of global variables such as `configdir`, `qscriptdir`, `templatesdir`, `logfilename`, ...

  Normally, the configuration is only loaded when the `gromacswrapper` package is imported but a re-reading of the configuration can be forced anytime by calling `get_configuration()`.

  `configuration`

    Dict of variables that we make available as globals in the module.

    Can be used as

        globals().update(GMXConfigParser.configuration)        # update configdir, templatesdir ...

  `getLogLevel`(section, option)

    Return the textual representation of logging level ‘option’ or the number.

    Note that option is always interpreted as an UPPERCASE string and hence integer log levels will not be recognized.

  `getpath`(section, option)

    Return option as an expanded path.

A subset of important data is also made available as top-level package variables as described under Location of template files (for historical reasons); the same variable are also available in the dict `gromacs.config.configuration`.

`gromacs.config.` `configuration` = {'templatesdir': '/Users/oliver/.gromacswrapper/templates', 'loglevel_file': 10, 'logfilename': 'gromacs.log', 'qscriptdir': '/Users/oliver/.gromacswrapper/qscripts', 'loglevel_console': 20, 'configfilename': '/Users/oliver/.gromacswrapper.cfg', 'path': ['.', '/Users/oliver/.gromacswrapper/qscripts', '/Users/oliver/.gromacswrapper/templates'], 'configdir': '/Users/oliver/.gromacswrapper'}

  Dict containing important configuration variables, populated by `get_configuration()` (mainly a shortcut; use `cfg` in most cases).

Default values are hard-coded in

`gromacs.config.` `CONFIGNAME` = '/Users/oliver/.gromacswrapper.cfg'

  Default name of the global configuration file.

`gromacs.config.` `defaults` = {'templatesdir': '/Users/oliver/.gromacswrapper/templates', 'loglevel_file': 'DEBUG', 'logfilename': 'gromacs.log', 'managerdir': '/Users/oliver/.gromacswrapper/managers', 'qscriptdir': '/Users/oliver/.gromacswrapper/qscripts', 'loglevel_console': 'INFO', 'configdir': '/Users/oliver/.gromacswrapper'}

  dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

  > (key, value) pairs

  dict(iterable) -> new dictionary initialized as if via:

    d = {} for k, v in iterable:

    > d[k] = v

  dict(**kwargs) -> new dictionary initialized with the name=value pairs
    in the keyword argument list. For example: dict(one=1, two=2)

### Accessing configuration and template files

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 `gromacs.config.path`, and finally within the package itself.

`gromacs.config.` `get_template`(t)

  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 `gromacs.config.path`,
  3. a filename in the package template directory (defined in the template dictionary `gromacs.config.templates`) or
  4. a key into `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: | `ValueError` if no file can be located.

`gromacs.config.` `get_templates`(t)

  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 `gromacs.config.path`,
  3. a filename in the package template directory (defined in the template dictionary `gromacs.config.templates`) or
  4. a key into `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: | `ValueError` if no file can be located.

## Logging

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

`gromacs.config.` `logfilename` = 'gromacs.log'

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

`gromacs.config.` `loglevel_console` = 20

  The default loglevel that is still printed to the console.

`gromacs.config.` `loglevel_file` = 10

  The default loglevel that is still written to the `logfilename`.

## Gromacs tools and scripts

Fundamentally, GromacsWrapper makes existing Gromacs tools (executables) available as functions. In order for this to work, these executables must be found in the environment of the Python process that runs GromacsWrapper, and the user must list all the tools that are to be made available.

### Setting up the environment

The standard way to set up the Gromacs environment is to source `GMXRC` in the shell before running the Python process. `GMXRC` adjusts a number of environment variables (such as `PATH` and `LD_LIBRARY_PATH`) but also sets Gromacs-specific environment variables such as `GMXBIN`, `GMXDATA`, and many others:

    source /usr/local/bin/GMXRC

(where the path to `GMXRC` is often set differently to disntinguish different installed versions of Gromacs).

Alternatively, GromacsWrapper can itself source a `GMXRC` file and set the environment with the `set_gmxrc_environment()` function. The path to a `GMXRC` file can be set in the config file in the `[Gromacs]` section as

> [Gromacs]

> GMXRC = /usr/local/bin/GMXRC

When GromacsWrapper starts up, it tries to set the environment using the `GMXRC` defined in the config file. If this is left empty or is not in the file, nothing is being done.

`gromacs.config.` `set_gmxrc_environment`(gmxrc)

  Set the environment from `GMXRC` provided in gmxrc.

  Runs `GMXRC` in a subprocess and puts environment variables loaded by it into this Python environment.

  If gmxrc evaluates to `False` then nothing is done. If errors occur then only a warning will be logged. Thus, it should be safe to just call this function.

### List of tools

The list of Gromacs tools can be specified in the config file in the `[Gromacs]` section with the `tools` variable.

The tool groups are a list of names that determines which tools are made available as classes in `gromacs.tools`. If not provided GromacsWrapper will first try to load Gromacs 5.x then Gromacs 4.x tools.

If you choose to provide a list, the Gromacs tools section of the config file can be like this:

    [Gromacs]
    # Release of the Gromacs package to which information in this sections applies.
    release = 4.5.3

    # 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.
    # (Note that this example has a much shorter list than the actual default.)
    tools =
          editconf make_ndx grompp genion genbox
          grompp pdb2gmx mdrun mdrun_d

    # which tool groups to make available
    groups = tools extra

For Gromacs 5.x use a section like the following, where driver commands are supplied:

    [Gromacs]
    # Release of the Gromacs package to which information in this sections applies.
    release = 5.0.5

    # GMXRC contains the path for GMXRC file which will be loaded. If not
    provided is expected that it was sourced as usual before importing this
    library.
    GMXRC = /usr/local/gromacs/bin/GMXRC

    # tools contains the command names of all Gromacs tools for which classes are generated.
    # Editing this list has only an effect when the package is reloaded.
    # (Note that this example has a much shorter list than the actual default.)
    tools = gmx gmx_d

For example, on the commandline you would run

    gmx grompp -f md.mdp -c system.gro -p topol.top -o md.tpr

and within GromacsWrapper this would become

    gromacs.grompp(f="md.mdp", c="system.gro", p="topol.top", o="md.tpr")

Note

Because of changes in the Gromacs tool in 5.x, GromacsWrapper scripts might break, even if the tool names are still the same.

## 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.

`gromacs.config.` `qscriptdir` = '/Users/oliver/.gromacswrapper/qscripts'

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

`gromacs.config.` `templatesdir` = '/Users/oliver/.gromacswrapper/templates'

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

`gromacs.config.` `managerdir` = '/Users/oliver/.gromacswrapper/managers'

  Directory to store configuration files for remote queuing systems `gromacs.qsub.Manager` instances. The default value is `~/.gromacswrapper/managers`.

`gromacs.config.` `templates` = {'md_OPLSAA.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/md_OPLSAA.mdp', 'em.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/em.mdp', 'darwin.sh': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/darwin.sh', 'gromacswrapper_465.cfg': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/gromacswrapper_465.cfg', 'gromacswrapper.cfg': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/gromacswrapper.cfg', 'md_G43a1.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/md_G43a1.mdp', 'local.sh': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/local.sh', 'md_CHARMM27.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/md_CHARMM27.mdp', 'md_CHARMM27_gpu.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/md_CHARMM27_gpu.mdp', 'md_OPLSAA_gpu.mdp': '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/md_OPLSAA_gpu.mdp'}

  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 `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 `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 `edit_mdp()`.

  > The safest bet is to use one of the `mdout.mdp` files produced by `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 `gromacs.config.qscriptdir`. See `gromacs.qsub` for the format and how these files are processed.

`gromacs.config.` `qscript_template` = '/Volumes/Data/oliver/Biop/Projects/Methods/GromacsWrapper/gromacs/templates/local.sh'

  The default template for SGE/PBS run scripts.