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  .. autofunction:: get_version_tuple 
167   
168  """ 
169  __docformat__ = "restructuredtext en" 
170   
171  #: Package version; this is the only place where it is set. 
172  VERSION = 0,1,10 
173   
174 -def get_version():
175 """Return current package version as a string.""" 176 return ".".join(map(str,VERSION))
177
178 -def get_version_tuple():
179 """Return current package version as a tuple (*MAJOR*, *MINOR*, *PATCHLEVEL*).""" 180 return tuple(VERSION)
181 182 # __all__ is extended with all gromacs command instances later 183 __all__ = ['config', 'tools', 'cbook'] 184 185 # Note: analysis not imported by default (requires additional pre-requisites) 186
187 -class GromacsError(EnvironmentError):
188 """Error raised when a gromacs tool fails. 189 190 Returns error code in the errno attribute and a string in strerror. 191 # TODO: return status code and possibly error message 192 """
193
194 -class MissingDataError(Exception):
195 """Error raised when prerequisite data are not available. 196 197 For analysis with :class:`gromacs.analysis.core.Simulation` this typically 198 means that the :meth:`~gromacs.analysis.core.Simulation.analyze` method has 199 to be run first. 200 """
201
202 -class ParseError(Exception):
203 """Error raised when parsing of a file failed."""
204
205 -class GromacsFailureWarning(Warning):
206 """Warning about failure of a Gromacs tool."""
207
208 -class GromacsImportWarning(ImportWarning):
209 """Warns about problems with using a gromacs tool."""
210
211 -class GromacsValueWarning(Warning):
212 """Warns about problems with the value of an option or variable."""
213
214 -class AutoCorrectionWarning(Warning):
215 """Warns about cases when the code is choosing new values automatically."""
216
217 -class BadParameterWarning(Warning):
218 """Warns if some parameters or variables are unlikely to be appropriate or correct."""
219
220 -class MissingDataWarning(Warning):
221 """Warns when prerequisite data/files are not available."""
222
223 -class UsageWarning(Warning):
224 """Warns if usage is unexpected/documentation ambiguous."""
225 226 import warnings 227 # These warnings should always be displayed because other parameters 228 # can have changed, eg during interactive use. 229 for w in (AutoCorrectionWarning, BadParameterWarning, UsageWarning, 230 GromacsFailureWarning, GromacsValueWarning): 231 warnings.simplefilter('always', category=w) 232 del w 233 234 235 # Import configuration before anything else 236 import config 237 238 239 import logging 240 # NOTE: logging is still iffy; when I reload I add a new logger each 241 # time and output is repeated for each reload. Probably should heed 242 # the advice on logging and libraries in 243 # http://docs.python.org/library/logging.html?#configuring-logging-for-a-library
244 -class NullHandler(logging.Handler):
245 - def emit(self, record):
246 pass
247 248 # default silent logger --- just here for illustration; below we 249 # we get a proper logger from log.create() 250 h = NullHandler() 251 logging.getLogger("gromacs").addHandler(h) 252 del h 253 254 # The top level logger of the library is named 'gromacs'. 255 # Note that we are configuring this logger with console output. If the root logger also 256 # does this then we will get two output lines to the console. We'll live with this because 257 # this is a simple convenience library and most people will not bother 258 # with a logger (I think...) 259 # 260 # In modules that use loggers get a logger like so: 261 # import logging 262 # logger = logging.getLogger('gromacs.MODULENAME') 263 264 # add standard logging -- remove when integrating in a library?? 265 import log 266 logger = log.create('gromacs', logfile='gromacs.log') 267 del log 268 269 270 # Add gromacs command **instances** to the top level. 271 # These serve as the equivalence of running commands in the shell. 272 # (Note that each gromacs command is actually run when the instance is 273 # created in order to gather the documentation string.) 274 import tools 275 276 # Ignore warnings from a few programs that do not produce 277 # documentation when run with '-h' (only applies when the default for 278 # failuremode of core.GromacsCommand is changed to 'warn') 279 warnings.simplefilter("ignore", GromacsFailureWarning) 280 _have_g_commands = [] 281 _missing_g_commands = [] 282 for clsname, cls in tools.registry.items(): 283 name = clsname[0].lower() + clsname[1:] # instances should start with lower case 284 try: 285 globals()[name] = cls() # add instance of command for immediate use 286 _have_g_commands.append(name) 287 except GromacsError: # ignore missing -h for doc extraction 288 pass 289 except OSError: 290 _missing_g_commands.append(name) 291 warnings.simplefilter("always", GromacsFailureWarning) 292 warnings.simplefilter("always", GromacsImportWarning) 293 294 _have_g_commands.sort() 295 _missing_g_commands.sort() 296 if len(_missing_g_commands) > 0: 297 warnings.warn("Some Gromacs commands were NOT found; " 298 "maybe source GMXRC first? The following are missing:\n%r\n" % _missing_g_commands, 299 category=GromacsImportWarning) 300 301 del name, cls, clsname 302 303 # get ALL active command instances with 'from gromacs import *' 304 __all__.extend(_have_g_commands) 305 306 307 # cbook should come after the whole of init as it relies on command 308 # instances in the top level name space 309 try: 310 import cbook 311 except OSError, err: 312 warnings.warn("Some Gromacs commands were NOT found when importing gromacs.cbook:\n"+str(err), 313 category=GromacsImportWarning) 314 315 # convenience functions for warnings 316 317 less_important_warnings = ['AutoCorrectionWarning', 'UsageWarning'] 318
319 -def filter_gromacs_warnings(action, categories=None):
320 """Set the :meth:`warnings.simplefilter` to *action*. 321 322 *categories* must be a list of warning classes or strings. 323 ``None`` selects the defaults, :data:`gromacs.less_important_warnings`. 324 """ 325 326 if categories is None: 327 categories = less_important_warnings 328 for c in categories: 329 try: 330 w = globals()[c] 331 except KeyError: 332 w = c 333 if not issubclass(w, Warning): 334 raise TypeError("%r is neither a Warning nor the name of a Gromacs warning." % c) 335 warnings.simplefilter(action, category=w)
336
337 -def disable_gromacs_warnings(categories=None):
338 """Disable ("ignore") specified warnings from the gromacs package. 339 340 *categories* must be a list of warning classes or strings. 341 ``None`` selects the defaults. 342 343 """ 344 filter_gromacs_warnings('ignore', categories=categories)
345
346 -def enable_gromacs_warnings(categories=None):
347 """Enable ("always") specified warnings from the gromacs package. 348 349 *categories* must be a list of warning classes or strings. 350 ``None`` selects the defaults, :data:`gromacs._less_important_warnings`. 351 352 """ 353 filter_gromacs_warnings('always', categories=categories)
354