1
2
3
4
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
172 VERSION = 0,1,10
173
175 """Return current package version as a string."""
176 return ".".join(map(str,VERSION))
177
179 """Return current package version as a tuple (*MAJOR*, *MINOR*, *PATCHLEVEL*)."""
180 return tuple(VERSION)
181
182
183 __all__ = ['config', 'tools', 'cbook']
184
185
186
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
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
203 """Error raised when parsing of a file failed."""
204
206 """Warning about failure of a Gromacs tool."""
207
209 """Warns about problems with using a gromacs tool."""
210
212 """Warns about problems with the value of an option or variable."""
213
215 """Warns about cases when the code is choosing new values automatically."""
216
218 """Warns if some parameters or variables are unlikely to be appropriate or correct."""
219
221 """Warns when prerequisite data/files are not available."""
222
224 """Warns if usage is unexpected/documentation ambiguous."""
225
226 import warnings
227
228
229 for w in (AutoCorrectionWarning, BadParameterWarning, UsageWarning,
230 GromacsFailureWarning, GromacsValueWarning):
231 warnings.simplefilter('always', category=w)
232 del w
233
234
235
236 import config
237
238
239 import logging
240
241
242
243
245 - def emit(self, record):
247
248
249
250 h = NullHandler()
251 logging.getLogger("gromacs").addHandler(h)
252 del h
253
254
255
256
257
258
259
260
261
262
263
264
265 import log
266 logger = log.create('gromacs', logfile='gromacs.log')
267 del log
268
269
270
271
272
273
274 import tools
275
276
277
278
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:]
284 try:
285 globals()[name] = cls()
286 _have_g_commands.append(name)
287 except GromacsError:
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
304 __all__.extend(_have_g_commands)
305
306
307
308
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
316
317 less_important_warnings = ['AutoCorrectionWarning', 'UsageWarning']
318
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
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
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