gromacs.config
– Configuration for GromacsWrapper¶
The config module provides configurable options for the whole package;
It mostly serves to define which gromacs tools and other scripts are
exposed in the gromacs
package and where template files are
located. The user can configure GromacsWrapper by
- editing the global configuration file
~/.gromacswrapper.cfg
- placing template files into directories under
~/.gromacswrapper
(gromacs.config.configdir
) which can be processed instead of the files that come with GromacsWrapper
In order to set up a basic configuration file and the directories
a user should execute gromacs.config.setup()
at least once. It
will prepare the user configurable area in their home directory and it
will generate a default global configuration file
~/.gromacswrapper.cfg
(the name is defined in
CONFIGNAME
):
import gromacs
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()
. Modifygromacs.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 withget_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.
- Create the global config file.
- 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 instancegromacswrapper.config.cfg
is updated as are a number of global variables such asconfigdir
,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 callingget_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.
Returns
True
if all files and directories are found andFalse
otherwise.Setting the environment variable
GROMACSWRAPPER_SUPPRESS_SETUP_CHECK
to ‘true’ (‘yes’ and ‘1’ also work) silence this function and make it always returnTrue
.Changed in version 0.3.1: Uses
GROMACSWRAPPER_SUPPRESS_SETUP_CHECK
to suppress output (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 ofGMXConfigParser
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 instancegromacswrapper.config.cfg
is updated as are a number of global variables such asconfigdir
,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 callingget_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.
-
getlist
(section, option, separator=None, sort=True)¶ Return option as a a list of strings.
Split on white space or separator. Sort for sort =
True
.
-
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; usecfg
in most cases).
Default values are hard-coded in
-
gromacs.config.
CONFIGNAME
= '/Users/oliver/.gromacswrapper.cfg'¶ 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'}¶ Holds the default values for important file and directory locations.
configdir
- Directory to store user templates and configurations.
The default value is
~/.gromacswrapper
. qscriptdir
- Directory to store user supplied queuing system scripts as
used by
gromacs.qsub
. The default value is~/.gromacswrapper/qscripts
. templatesdir
- Directory to store user supplied template files such as mdp files.
The default value is
~/.gromacswrapper/templates
. managerdir
- Directory to store configuration files for different queuing system
managers as used in
gromacs.manager
. The default value is~/.gromacswrapper/managers
.
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
- a relative or absolute path,
- a file in one of the directories listed in
gromacs.config.path
, - a filename in the package template directory (defined in the template dictionary
gromacs.config.templates
) or - 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
- a relative or absolute path,
- a file in one of the directories listed in
gromacs.config.path
, - a filename in the package template directory (defined in the template dictionary
gromacs.config.templates
) or - 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
andgromacs.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¶
load_*
variables are lists that contain instructions to other
parts of the code which packages and scripts should be wrapped.
-
gromacs.config.
load_tools
= ['demux.pl', 'do_dssp', 'editconf', 'eneconv', 'g_anadock', 'g_anaeig', 'g_analyze', 'g_angle', 'g_bar', 'g_bond', 'g_bundle', 'g_chi', 'g_cluster', 'g_clustsize', 'g_confrms', 'g_covar', 'g_current', 'g_density', 'g_densmap', 'g_dielectric', 'g_dih', 'g_dipoles', 'g_disre', 'g_dist', 'g_dyndom', 'g_enemat', 'g_energy', 'g_filter', 'g_gyrate', 'g_h2order', 'g_hbond', 'g_helix', 'g_helixorient', 'g_kinetics', 'g_lie', 'g_luck', 'g_mdmat', 'g_membed', 'g_mindist', 'g_morph', 'g_msd', 'g_nmeig', 'g_nmens', 'g_nmtraj', 'g_order', 'g_pme_error', 'g_polystat', 'g_potential', 'g_principal', 'g_protonate', 'g_rama', 'g_rdf', 'g_rms', 'g_rmsdist', 'g_rmsf', 'g_rotacf', 'g_rotmat', 'g_saltbr', 'g_sas', 'g_select', 'g_sgangle', 'g_sham', 'g_sigeps', 'g_sorient', 'g_spatial', 'g_spol', 'g_tcaf', 'g_traj', 'g_tune_pme', 'g_vanhove', 'g_velacc', 'g_wham', 'g_wheel', 'g_x2top', 'genbox', 'genconf', 'genion', 'genrestr', 'gmxcheck', 'gmxdump', 'grompp', 'make_edi', 'make_ndx', 'mdrun', 'mdrun_d', 'mk_angndx', 'pdb2gmx', 'tpbconv', 'trjcat', 'trjconv', 'trjorder', 'xplor2gmx.pl', 'xpm2ps', 'a_gridcalc', 'a_ri3Dc', 'g_count', 'g_flux', 'g_ri3Dc']¶ Python list of all tool file names. Filled from values in the tool groups in the configuration file.
load_tools
is populated from lists of executable names in the
configuration file.
The tool groups are strings that contain white-space separated file
names of Gromacs tools. These lists determine which tools are made
available as classes in gromacs.tools
.
A typical Gromacs tools section of the config file looks 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
# Additional gromacs tools that should be made available.
extra =
g_count g_flux
a_gridcalc a_ri3Dc g_ri3Dc
# which tool groups to make available as gromacs.NAME
groups = tools extra
For Gromacs 5.x use a section like the following, where the driver
command gmx
is added as a prefix:
[Gromacs]
# Release of the Gromacs package to which information in this sections applies.
release = 5.0.5
# 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:editconf gmx:make_ndx gmx:grompp gmx:genion gmx:solvate
gmx:insert-molecule gmx:convert-tpr
gmx:grompp gmx:pdb2gmx gmx:mdrun
# which tool groups to make available as gromacs.NAME
groups = tools
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")
(The driver command is stripped and only the “command name” is used to identify the command. This makes it easier to migrate GromacsWrapper scripts from Gromacs 4.x to 5.x.).
The driver command can be changed per-tool, allowing for mpi and non-mpi versions to be used. For example:
tools = gmx_mpi:mdrun gmx:pdb2gmx
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': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/md_OPLSAA.mdp', 'em.mdp': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/em.mdp', 'darwin.sh': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/darwin.sh', 'hector.pbs': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/hector.pbs', 'neuron.sge': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/neuron.sge', 'deathspud.sge': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/deathspud.sge', 'hpcx.ll': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/hpcx.ll', 'md_OPLSAA_gpu.mdp': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/md_OPLSAA_gpu.mdp', 'gromacswrapper.cfg': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/gromacswrapper.cfg', 'glial451.pbs': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/glial451.pbs', 'md_G43a1.mdp': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/md_G43a1.mdp', 'local.sh': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/local.sh', 'md_CHARMM27.mdp': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/md_CHARMM27.mdp', 'astrocyte.sge': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/astrocyte.sge', 'jade.pbs': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/jade.pbs', 'md_CHARMM27_gpu.mdp': '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/md_CHARMM27_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 withedit_mdp()
.The safest bet is to use one of the
mdout.mdp
files produced bygromacs.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 intogromacs.config.qscriptdir
. Seegromacs.qsub
for the format and how these files are processed.
-
gromacs.config.
qscript_template
= '/Users/oliver/.virtualenvs/gromacswrapper/develop/lib/python2.7/site-packages/gromacs/templates/local.sh'¶ The default template for SGE/PBS run scripts.