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
167 """
168 __docformat__ = "restructuredtext en"
169
170
171 VERSION = "0.1.9"
172
174 """Return current package version as a string."""
175 return VERSION
176
177
178 __all__ = ['config', 'tools', 'cbook']
179
180
181
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
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
198 """Error raised when parsing of a file failed."""
199
201 """Warning about failure of a Gromacs tool."""
202
204 """Warns about problems with using a gromacs tool."""
205
207 """Warns about problems with the value of an option or variable."""
208
210 """Warns about cases when the code is choosing new values automatically."""
211
213 """Warns if some parameters or variables are unlikely to be appropriate or correct."""
214
216 """Warns when prerequisite data/files are not available."""
217
219 """Warns if usage is unexpected/documentation ambiguous."""
220
221 import warnings
222
223
224 for w in (AutoCorrectionWarning, BadParameterWarning, UsageWarning,
225 GromacsFailureWarning, GromacsValueWarning):
226 warnings.simplefilter('always', category=w)
227 del w
228
229
230
231 import config
232
233
234 import logging
235
236
237
238
240 - def emit(self, record):
242
243
244
245 h = NullHandler()
246 logging.getLogger("gromacs").addHandler(h)
247 del h
248
249
250
251
252
253
254
255
256
257
258
259
260 import log
261 logger = log.create('gromacs', logfile='gromacs.log')
262 del log
263
264
265
266
267
268
269 import tools
270
271
272
273
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:]
279 try:
280 globals()[name] = cls()
281 _have_g_commands.append(name)
282 except GromacsError:
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
299 __all__.extend(_have_g_commands)
300
301
302
303
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
311
312 less_important_warnings = ['AutoCorrectionWarning', 'UsageWarning']
313
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
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
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