gromacs.config

Source Code for Module gromacs.config

1 # GromacsWrapper config.py 2 # Copyright (c) 2009 Oliver Beckstein <orbeckst@gmail.com> 3 # Released under the GNU Public License 3 (or higher, your choice) 4 # See the file COPYING for details. 5 6 """ 7 :mod:`gromacs.config` -- Configuration for GromacsWrapper 8 ========================================================== 9 10 The config module provides configurable options for the whole package; 11 eventually it might grow into a sophisticated configuration system such as 12 matplotlib's rc system but right now it mostly serves to define which gromacs 13 tools and other scripts are offered in the package and where template files are 14 located. If the user wants to change anything they will still have to do it 15 here in source until a better mechanism with rc files has been implemented. 16 17 User-supplied templates are stored under 18 :data:`gromacs.config.configdir`. Eventually this will also contain the 19 configuration options currently hard-coded in :mod:`gromacs.config`. 20 21 .. autodata:: configdir 22 .. autodata:: path 23 24 The user should execute :func:`gromacs.config.setup` at least once to 25 prepare the user configurable area in their home directory:: 26 27 import gromacs 28 gromacs.config.setup() 29 30 31 Logging 32 ------- 33 34 Gromacs commands log their invocation to a log file; typically at 35 loglevel *INFO* (see the python `logging module`_ for details). 36 37 .. autodata:: logfilename 38 .. autodata:: loglevel_console 39 .. autodata:: loglevel_file 40 41 .. _logging module: http://docs.python.org/library/logging.html 42 43 44 Gromacs tools and scripts 45 ------------------------- 46 47 ``load_*`` variables are lists that contain instructions to other 48 parts of the code which packages and scripts should be wrapped. 49 50 .. autodata:: load_tools 51 .. autodata:: load_scripts 52 53 :data:`load_tools` is populated by listing ``gmx_*`` tool group variables in 54 :data:`gmx_tool_groups`. 55 56 .. autodata:: gmx_tool_groups 57 58 The tool groups variables are strings that contain white-space separated file 59 names of Gromacs tools. These lists determine which tools are made available as 60 classes in :mod:`gromacs.tools`. 61 62 .. autodata:: gmx_tools 63 .. autodata:: gmx_extra_tools 64 65 66 Location of template files 67 -------------------------- 68 69 *Template variables* list files in the package that can be used as 70 templates such as run input files. Because the package can be a zipped 71 egg we actually have to unwrap these files at this stage but this is 72 completely transparent to the user. 73 74 .. autodata:: qscriptdir 75 .. autodata:: templatesdir 76 .. autodata:: templates 77 .. autodata:: qscript_template 78 .. autofunction:: setup 79 80 Accessing configuration data 81 ---------------------------- 82 83 The following functions can be used to access configuration data. Note that 84 files are searched first with their full filename, then in all directories 85 listed in :data:`gromacs.config.path`, and finally within the package itself. 86 87 .. autofunction:: get_template 88 .. autofunction:: get_templates 89 90 """ 91 92 import os 93 from pkg_resources import resource_filename, resource_listdir 94 95 import utilities 96 97 # Logging 98 # ------- 99 import logging 100 101 #: File name for the log file; all gromacs command and many utility functions (e.g. in 102 #: :mod:`gromacs.cbook` and :mod:`gromacs.setup`) append messages there. Warnings and 103 #: errors are also recorded here. The default is *gromacs.log*. 104 logfilename = "gromacs.log" 105 106 #: The default loglevel that is still printed to the console. 107 loglevel_console = logging.INFO 108 109 #: The default loglevel that is still written to the :data:`logfilename`. 110 loglevel_file = logging.DEBUG 111 112 113 # User-accessible configuration 114 # ----------------------------- 115 116 #: Directory to store user templates and rc files. 117 #: The default value is ``~/.gromacswrapper``. 118 configdir = os.path.expanduser(os.path.join("~",".gromacswrapper")) 119 120 #: Directory to store user supplied queuing system scripts. 121 #: The default value is ``~/.gromacswrapper/qscripts``. 122 qscriptdir = os.path.join(configdir, 'qscripts') 123 124 #: Directory to store user supplied template files such as mdp files. 125 #: The default value is ``~/.gromacswrapper/templates``. 126 templatesdir = os.path.join(configdir, 'templates') 127

128 -def setup():

129 """Create the directories in which the user can store template and config files. 130 131 This function can be run repeatedly without harm. 132 """ 133 # setup() must be separate and NOT run automatically when config 134 # is loaded so that easy_install installations work 135 # (otherwise we get a sandbox violation) 136 utilities.mkdir_p(configdir) 137 utilities.mkdir_p(qscriptdir) 138 utilities.mkdir_p(templatesdir)

139

140 -def check_setup():

141 """Check if templates directories are setup and issue a warning and help.""" 142 missing = [d for d in (configdir, qscriptdir, templatesdir) 143 if not os.path.exists(d)] 144 if len(missing) > 0: 145 print "NOTE: Some configuration directories are not set up yet" 146 print " %r" % missing 147 print " You can create them with the command" 148 print " >>> gromacs.config.setup()" 149 return len(missing) == 0

150 check_setup() 151 152 153 #: Search path for user queuing scripts and templates. The internal package-supplied 154 #: templates are always searched last via :func:`gromacs.config.get_templates`. 155 #: Modify :data:`gromacs.config.path` directly in order to customize the template 156 #: and qscript searching. By default it has the value ``['.', qscriptdir, 157 #: templatesdir]``. 158 #: (Note that it is not a good idea to have template files and qscripts with the 159 #: same name as they are both searched on the same path.) 160 path = [os.path.curdir, qscriptdir, templatesdir] 161 162 # Gromacs tools 163 # ------------- 164 165 #: List of the variables in gromacs.tools that should be loaded. Possible values: 166 #: *gmx_tools*, *gmx_extra_tools*. Right now these are variable names in 167 #: :mod:`gromacs.config`, referencing :data:`gromacs.config.gmx_tools` and 168 #: :data:`gromacs.config.gmx_extra_tools`. 169 gmx_tool_groups = ['gmx_tools', 'gmx_extra_tools' ] 170 171 #: Contains the file names of all Gromacs tools for which classes are generated. 172 #: Editing this list has only an effect when the package is reloaded. If you want 173 #: additional tools then add the, to the source (``config.py``) or derive new 174 #: classes manually from :class:`gromacs.core.GromacsCommand`. (Eventually, this 175 #: functionality will be in a per-user configurable file.) The current list was 176 #: generated from Gromacs 4.0.99 (git). 177 #: Removed (because of various issues) 178 #: - g_kinetics 179 gmx_tools = """\ 180 anadock g_current g_helix g_rama g_traj mdrun_d 181 g_density g_helixorient g_rdf g_vanhove mk_angndx 182 do_dssp g_densmap g_rms g_velacc pdb2gmx 183 editconf g_dielectric g_lie g_wham protonate 184 eneconv g_dih g_mdmat g_rmsf genbox sigeps 185 g_anaeig g_dipoles g_mindist g_rotacf genconf tpbconv 186 g_analyze g_disre g_morph g_saltbr genion trjcat 187 g_angle g_dist g_msd g_sas genrestr trjconv 188 g_bond g_dyndom g_nmeig g_sdf gmxcheck trjorder 189 g_bundle g_enemat g_nmens g_sgangle gmxdump wheel 190 g_chi g_energy g_nmtraj g_sham grompp x2top 191 g_cluster g_filter g_order g_sorient luck 192 g_clustsize g_gyrate g_polystat g_spatial make_edi xpm2ps 193 g_confrms g_h2order g_potential g_spol make_ndx 194 g_covar g_hbond g_principal g_tcaf mdrun 195 """ 196 197 gmx_tools_402 = """\ 198 anadock g_current g_helix g_rama g_traj mdrun_d 199 demux.pl g_density g_helixorient g_rdf g_vanhove mk_angndx 200 do_dssp g_densmap g_kinetics g_rms g_velacc pdb2gmx 201 editconf g_dielectric g_lie g_rmsdist g_wham protonate 202 eneconv g_dih g_mdmat g_rmsf genbox sigeps 203 g_anaeig g_dipoles g_mindist g_rotacf genconf tpbconv 204 g_analyze g_disre g_morph g_saltbr genion trjcat 205 g_angle g_dist g_msd g_sas genrestr trjconv 206 g_bond g_dyndom g_nmeig g_sdf gmxcheck trjorder 207 g_bundle g_enemat g_nmens g_sgangle gmxdump wheel 208 g_chi g_energy g_nmtraj g_sham grompp x2top 209 g_cluster g_filter g_order g_sorient luck xplor2gmx.pl 210 g_clustsize g_gyrate g_polystat g_spatial make_edi xpm2ps 211 g_confrms g_h2order g_potential g_spol make_ndx 212 g_covar g_hbond g_principal g_tcaf mdrun 213 """ 214 215 216 #: Additional gromacs tools (add *gmx_extra_tools* to 217 #: :data:`gromacs.config.gmx_tool_groups` to enable them, provided the binaries 218 #: have been provided on the :envvar:`PATH`). 219 gmx_extra_tools = """\ 220 g_count g_flux g_zcoord 221 g_ri3Dc a_ri3Dc a_gridcalc 222 """ 223 224 #: Python list of all tool file names. Automatically filled from :data:`gmx_tools` 225 #: and :data:`gmx_extra_tools`, depending on the values in 226 #: :data:`gmx_tool_groups`. 227 load_tools = [] 228 229 for g in gmx_tool_groups: 230 load_tools.extend(globals()[g].split()) 231 del g 232 233 # Adding additional 3rd party scripts 234 # ----------------------------------- 235 236 # HACK-Alert: we're temporarily "installing" scripts from the egg ... this is a hack: 237 # Must extract because it is part of a zipped python egg; 238 # see http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources 239 GridMAT_MD = resource_filename(__name__,'external/GridMAT-MD_v1.0.2/GridMAT-MD.pl') 240 os.chmod(GridMAT_MD, 0755) 241 242 243 #: 3rd party analysis scripts and tools; this is a list of triplets of 244 #: 245 #: (*script name/path*, *command name*, *doc string*) 246 #: 247 #: (See the source code for examples.) 248 load_scripts = [ 249 (GridMAT_MD, 250 'GridMAT_MD', 251 """GridMAT-MD: A Grid-based Membrane Analysis Tool for use with Molecular Dynamics. 252 253 *This* ``GridMAT-MD`` is a patched version of the original 254 ``GridMAT-MD.pl`` v1.0.2, written by WJ Allen, JA Lemkul and DR 255 Bevan. The original version is available from the `GridMAT-MD`_ home 256 page, 257 258 .. _`GridMAT-MD`: http://www.bevanlab.biochem.vt.edu/GridMAT-MD/index.html 259 260 Please cite 261 262 W. J. Allen, J. A. Lemkul, and D. R. Bevan. (2009) "GridMAT-MD: A 263 Grid-based Membrane Analysis Tool for Use With Molecular Dynamics." 264 J. Comput. Chem. 30 (12): 1952-1958. 265 266 when using this programme. 267 268 Usage: 269 270 .. class:: GridMAT_MD(config[,structure]) 271 272 :Arguments: 273 - *config* : See the original documentation for a description for the 274 configuration file. 275 - *structure* : A gro or pdb file that overrides the value for 276 *bilayer* in the configuration file. 277 278 """), 279 ] 280 281 282 # Location of template files 283 # -------------------------- 284

285 -def _generate_template_dict(dirname):

286 """Generate a list of included files *and* extract them to a temp space. 287 288 Templates have to be extracted from the egg because they are used 289 by external code. All template filenames are stored in 290 :data:`config.templates`. 291 """ 292 return dict((resource_basename(fn), resource_filename(__name__, dirname+'/'+fn)) 293 for fn in resource_listdir(__name__, dirname) 294 if not fn.endswith('~'))

295

296 -def resource_basename(resource):

297 """Last component of a resource (which always uses '/' as sep).""" 298 if resource.endswith('/'): 299 resource = resource[:-1] 300 parts = resource.split('/') 301 return parts[-1]

302 303 templates = _generate_template_dict('templates') 304 """*GromacsWrapper* comes with a number of templates for run input files 305 and queuing system scripts. They are provided as a convenience and 306 examples but **WITHOUT ANY GUARANTEE FOR CORRECTNESS OR SUITABILITY FOR 307 ANY PURPOSE**. 308 309 All template filenames are stored in 310 :data:`gromacs.config.templates`. Templates have to be extracted from 311 the GromacsWrapper python egg file because they are used by external 312 code: find the actual file locations from this variable. 313 314 **Gromacs mdp templates** 315 316 These are supplied as examples and there is **NO GUARANTEE THAT THEY 317 PRODUCE SENSIBLE OUTPUT** --- check for yourself! Note that only 318 existing parameter names can be modified with 319 :func:`gromacs.cbook.edit_mdp` at the moment; if in doubt add the 320 parameter with its gromacs default value (or empty values) and 321 modify later with :func:`~gromacs.cbook.edit_mdp`. 322 323 The safest bet is to use one of the ``mdout.mdp`` files produced by 324 :func:`gromacs.grompp` as a template as this mdp contains all 325 parameters that are legal in the current version of Gromacs. 326 327 **Queuing system templates** 328 329 The queing system scripts are highly specific and you will need to add your 330 own into :data:`gromacs.config.qscriptdir`. 331 See :mod:`gromacs.qsub` for the format and how these files are processed. 332 """ 333 334 #: The default template for SGE/PBS run scripts. 335 qscript_template = templates['local.sh'] 336 337 338 # Functions to access configuration data 339 # -------------------------------------- 340

341 -def get_template(t):

342 """Find template file *t* and return its real path. 343 344 *t* can be a single string or a list of strings. A string 345 should be one of 346 347 1. a relative or absolute path, 348 2. a file in one of the directories listed in :data:`gromacs.config.path`, 349 3. a filename in the package template directory (defined in the template dictionary 350 :data:`gromacs.config.templates`) or 351 4. a key into :data:`~gromacs.config.templates`. 352 353 The first match (in this order) is returned. If the argument is a 354 single string then a single string is returned, otherwise a list 355 of strings. 356 357 :Arguments: *t* : template file or key (string or list of strings) 358 :Returns: os.path.realpath(*t*) (or a list thereof) 359 :Raises: :exc:`ValueError` if no file can be located. 360 361 """ 362 templates = [_get_template(s) for s in utilities.asiterable(t)] 363 if len(templates) == 1: 364 return templates[0] 365 return templates

366

367 -def get_templates(t):

368 """Find template file(s) *t* and return their real paths. 369 370 *t* can be a single string or a list of strings. A string should 371 be one of 372 373 1. a relative or absolute path, 374 2. a file in one of the directories listed in :data:`gromacs.config.path`, 375 3. a filename in the package template directory (defined in the template dictionary 376 :data:`gromacs.config.templates`) or 377 4. a key into :data:`~gromacs.config.templates`. 378 379 The first match (in this order) is returned for each input argument. 380 381 :Arguments: *t* : template file or key (string or list of strings) 382 :Returns: list of os.path.realpath(*t*) 383 :Raises: :exc:`ValueError` if no file can be located. 384 385 """ 386 return [_get_template(s) for s in utilities.asiterable(t)]

387

388 -def _get_template(t):

389 """Return a single template *t*.""" 390 if os.path.exists(t): # 1) Is it an accessible file? 391 pass 392 else: 393 _t = t 394 _t_found = False 395 for d in path: # 2) search config.path 396 p = os.path.join(d, _t) 397 if os.path.exists(p): 398 t = p 399 _t_found = True 400 break 401 _t = os.path.basename(t) 402 if not _t_found: # 3) try template dirs 403 for p in templates.values(): 404 if _t == os.path.basename(p): 405 t = p 406 _t_found = True # NOTE: in principle this could match multiple 407 break # times if more than one template dir existed. 408 if not _t_found: # 4) try it as a key into templates 409 try: 410 t = templates[t] 411 except KeyError: 412 pass 413 else: 414 _t_found = True 415 if not _t_found: # 5) nothing else to try... 416 raise ValueError("Failed to locate the template file %(t)r." % vars()) 417 return os.path.realpath(t)

418