Package gromacs
[hide private]
[frames] | no frames]

Source Code for Package gromacs

  1  # GromacsWrapper 
  2  # Copyright (c) 2009-2010 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` -- GromacsWrapper Package Overview 
  8  ================================================= 
  9   
 10  **GromacsWrapper** (package :mod:`gromacs`) is a thin shell around the `Gromacs`_ 
 11  tools for light-weight integration into python scripts or interactive use in 
 12  `ipython`_. 
 13   
 14  .. _`Gromacs`: http://www.gromacs.org 
 15  .. _`ipython`: http://ipython.scipy.org 
 16   
 17   
 18  Modules 
 19  ------- 
 20   
 21  :mod:`gromacs` 
 22       The top level module contains all gromacs tools; each tool can be 
 23       run directly or queried for its documentation. It also defines 
 24       the root logger class (name *gromacs* by default). 
 25   
 26  :mod:`gromacs.config` 
 27       Configuration options. Not really used much at the moment. 
 28   
 29  :mod:`gromacs.cbook` 
 30       The Gromacs cook book contains typical applications of the tools. In many 
 31       cases this not more than just an often-used combination of parameters for 
 32       a tool. 
 33   
 34  :mod:`gromacs.tools` 
 35       Contains classes that wrap the gromacs tools. They are automatically 
 36       generated from the list of tools in :data:`gromacs.tools.gmx_tools`. 
 37   
 38  :mod:`gromacs.formats` 
 39       Classes to represent data files in various formats such as 
 40       xmgrace graphs. The classes allow reading and writing and for 
 41       graphs, also plotting of the data. 
 42   
 43  :mod:`gromacs.utilities` 
 44       Convenience functions and mixin-classes that are used as helpers 
 45       in other modules. 
 46   
 47  :mod:`gromacs.setup` 
 48       Functions to set up a MD simulation, containing tasks such as solvation 
 49       and adding ions, energy minimizqtion, MD with position-restraints, and 
 50       equilibrium MD. 
 51   
 52  :mod:`gromacs.qsub` 
 53       Functions to handle batch submission queuing systems. 
 54   
 55  :mod:`gromacs.run` 
 56       Classes to run :program:`mdrun` in various way, including on 
 57       multiprocessor systems. 
 58   
 59  :mod:`gromacs.analysis` 
 60       A package that collects whole analysis tasks. It uses the gromacs but is 
 61       otherwise only loosely coupled with the rest. At the moment it only 
 62       contains the infrastructure and an example application. See the package 
 63       documentation. 
 64   
 65   
 66  Examples 
 67  -------- 
 68   
 69  The following examples should simply convey the flavour of using the 
 70  package. See the individual modules for more examples. 
 71   
 72  Getting help 
 73  ............ 
 74   
 75  In python:: 
 76   
 77     help(gromacs.g_dist) 
 78     gromacs.g_dist.help() 
 79     gromacs.g_dist.help(long=True) 
 80   
 81  In ``ipython``:: 
 82   
 83     gromacs.g_dist ? 
 84   
 85   
 86  Simple usage 
 87  ............ 
 88   
 89  Gromacs flags are given as python keyword arguments:: 
 90   
 91     gromacs.g_dist(v=True, s='topol.tpr', f='md.xtc', o='dist.xvg', dist=1.2) 
 92   
 93  Input to stdin of the command can be supplied:: 
 94   
 95     gromacs.make_ndx(f='topol.tpr', o='md.ndx',  
 96                      input=('keep "SOL"', '"SOL" | r NA | r CL', 'name 2 solvent', 'q')) 
 97   
 98  Output of the command can be caught in a variable and analyzed:: 
 99   
100     rc, output, junk = gromacs.grompp(..., stdout=False)        # collects command output 
101     for line in output.split('\\n'): 
102         line = line.strip() 
103         if line.startswith('System has non-zero total charge:'): 
104               qtot = float(line[34:]) 
105               break 
106   
107  (See :func:`gromacs.cbook.grompp_qtot` for a more robust implementation of this 
108  application.) 
109   
110   
111  Warnings and Exceptions 
112  ----------------------- 
113   
114  A number of package-specific exceptions (:exc:`GromacsError`) and 
115  warnings (:exc:`Gromacs*Warning`, :exc:`AutoCorrectionWarning`, 
116  :exc:`BadParameterWarning`) can be raised. 
117   
118  If you want to stop execution at, for instance, a :exc:`AutoCorrectionWarning` or 
119  :exc:`BadParameterWarning` then use the python :mod:`warnings` filter:: 
120    
121    import warnings 
122    warnings.simplefilter('error', gromacs.AutoCorrectionWarning) 
123    warnings.simplefilter('error', gromacs.BadParameterWarning) 
124   
125  This will make python raise an exception instead of moving on. The default is 
126  to always report, eg:: 
127   
128    warnings.simplefilter('always', gromacs.BadParameterWarning) 
129   
130  The following *exceptions* are defined: 
131   
132  .. autoexception:: GromacsError 
133  .. autoexception:: MissingDataError 
134  .. autoexception:: ParseError 
135   
136  The following *warnings* are defined: 
137   
138  .. autoexception:: GromacsFailureWarning 
139  .. autoexception:: GromacsImportWarning 
140  .. autoexception:: GromacsValueWarning 
141  .. autoexception:: AutoCorrectionWarning 
142  .. autoexception:: BadParameterWarning 
143  .. autoexception:: MissingDataWarning 
144  .. autoexception:: UsageWarning 
145   
146   
147  Logging 
148  ------- 
149   
150  The library uses python's logging_ module to keep a history of what it has been 
151  doing. In particular, every wrapped Gromacs command logs its command line 
152  (including piped input) to the log file (configured in 
153  :data:`gromacs.config.logfilename`). This facilitates debugging or simple 
154  re-use of command lines for very quick and dirty work. The logging facilty 
155  appends to the log file and time-stamps every entry. See :mod:`gromacs.config` 
156  for more details on configuration. 
157   
158  .. _logging: http://docs.python.org/library/logging.html 
159   
160  Version 
161  ------- 
162   
163  The package version can be queried with the :func:`gromacs.get_version` function. 
164   
165  .. autofunction:: get_version 
166   
167  """ 
168  __docformat__ = "restructuredtext en" 
169   
170  #: Package version; this is the only place where it is set. 
171  VERSION = "0.1.9" 
172   
173 -def get_version():
174 """Return current package version as a string.""" 175 return VERSION
176 177 # __all__ is extended with all gromacs command instances later 178 __all__ = ['config', 'tools', 'cbook'] 179 180 # Note: analysis not imported by default (requires additional pre-requisites) 181
182 -class GromacsError(EnvironmentError):
183 """Error raised when a gromacs tool fails. 184 185 Returns error code in the errno attribute and a string in strerror. 186 # TODO: return status code and possibly error message 187 """
188
189 -class MissingDataError(Exception):
190 """Error raised when prerequisite data are not available. 191 192 For analysis with :class:`gromacs.analysis.core.Simulation` this typically 193 means that the :meth:`~gromacs.analysis.core.Simulation.analyze` method has 194 to be run first. 195 """
196
197 -class ParseError(Exception):
198 """Error raised when parsing of a file failed."""
199
200 -class GromacsFailureWarning(Warning):
201 """Warning about failure of a Gromacs tool."""
202
203 -class GromacsImportWarning(ImportWarning):
204 """Warns about problems with using a gromacs tool."""
205
206 -class GromacsValueWarning(Warning):
207 """Warns about problems with the value of an option or variable."""
208
209 -class AutoCorrectionWarning(Warning):
210 """Warns about cases when the code is choosing new values automatically."""
211
212 -class BadParameterWarning(Warning):
213 """Warns if some parameters or variables are unlikely to be appropriate or correct."""
214
215 -class MissingDataWarning(Warning):
216 """Warns when prerequisite data/files are not available."""
217
218 -class UsageWarning(Warning):
219 """Warns if usage is unexpected/documentation ambiguous."""
220 221 import warnings 222 # These warnings should always be displayed because other parameters 223 # can have changed, eg during interactive use. 224 for w in (AutoCorrectionWarning, BadParameterWarning, UsageWarning, 225 GromacsFailureWarning, GromacsValueWarning): 226 warnings.simplefilter('always', category=w) 227 del w 228 229 230 # Import configuration before anything else 231 import config 232 233 234 import logging 235 # NOTE: logging is still iffy; when I reload I add a new logger each 236 # time and output is repeated for each reload. Probably should heed 237 # the advice on logging and libraries in 238 # http://docs.python.org/library/logging.html?#configuring-logging-for-a-library
239 -class NullHandler(logging.Handler):
240 - def emit(self, record):
241 pass
242 243 # default silent logger --- just here for illustration; below we 244 # we get a proper logger from log.create() 245 h = NullHandler() 246 logging.getLogger("gromacs").addHandler(h) 247 del h 248 249 # The top level logger of the library is named 'gromacs'. 250 # Note that we are configuring this logger with console output. If the root logger also 251 # does this then we will get two output lines to the console. We'll live with this because 252 # this is a simple convenience library and most people will not bother 253 # with a logger (I think...) 254 # 255 # In modules that use loggers get a logger like so: 256 # import logging 257 # logger = logging.getLogger('gromacs.MODULENAME') 258 259 # add standard logging -- remove when integrating in a library?? 260 import log 261 logger = log.create('gromacs', logfile='gromacs.log') 262 del log 263 264 265 # Add gromacs command **instances** to the top level. 266 # These serve as the equivalence of running commands in the shell. 267 # (Note that each gromacs command is actually run when the instance is 268 # created in order to gather the documentation string.) 269 import tools 270 271 # Ignore warnings from a few programs that do not produce 272 # documentation when run with '-h' (only applies when the default for 273 # failuremode of core.GromacsCommand is changed to 'warn') 274 warnings.simplefilter("ignore", GromacsFailureWarning) 275 _have_g_commands = [] 276 _missing_g_commands = [] 277 for clsname, cls in tools.registry.items(): 278 name = clsname[0].lower() + clsname[1:] # instances should start with lower case 279 try: 280 globals()[name] = cls() # add instance of command for immediate use 281 _have_g_commands.append(name) 282 except GromacsError: # ignore missing -h for doc extraction 283 pass 284 except OSError: 285 _missing_g_commands.append(name) 286 warnings.simplefilter("always", GromacsFailureWarning) 287 warnings.simplefilter("always", GromacsImportWarning) 288 289 _have_g_commands.sort() 290 _missing_g_commands.sort() 291 if len(_missing_g_commands) > 0: 292 warnings.warn("Some Gromacs commands were NOT found; " 293 "maybe source GMXRC first? The following are missing:\n%r\n" % _missing_g_commands, 294 category=GromacsImportWarning) 295 296 del name, cls, clsname 297 298 # get ALL active command instances with 'from gromacs import *' 299 __all__.extend(_have_g_commands) 300 301 302 # cbook should come after the whole of init as it relies on command 303 # instances in the top level name space 304 try: 305 import cbook 306 except OSError, err: 307 warnings.warn("Some Gromacs commands were NOT found when importing gromacs.cbook:\n"+str(err), 308 category=GromacsImportWarning) 309 310 # convenience functions for warnings 311 312 less_important_warnings = ['AutoCorrectionWarning', 'UsageWarning'] 313
314 -def filter_gromacs_warnings(action, categories=None):
315 """Set the :meth:`warnings.simplefilter` to *action*. 316 317 *categories* must be a list of warning classes or strings. 318 ``None`` selects the defaults, :data:`gromacs.less_important_warnings`. 319 """ 320 321 if categories is None: 322 categories = less_important_warnings 323 for c in categories: 324 try: 325 w = globals()[c] 326 except KeyError: 327 w = c 328 if not issubclass(w, Warning): 329 raise TypeError("%r is neither a Warning nor the name of a Gromacs warning." % c) 330 warnings.simplefilter(action, category=w)
331
332 -def disable_gromacs_warnings(categories=None):
333 """Disable ("ignore") specified warnings from the gromacs package. 334 335 *categories* must be a list of warning classes or strings. 336 ``None`` selects the defaults. 337 338 """ 339 filter_gromacs_warnings('ignore', categories=categories)
340
341 -def enable_gromacs_warnings(categories=None):
342 """Enable ("always") specified warnings from the gromacs package. 343 344 *categories* must be a list of warning classes or strings. 345 ``None`` selects the defaults, :data:`gromacs._less_important_warnings`. 346 347 """ 348 filter_gromacs_warnings('always', categories=categories)
349