gromacs.utilities – Helper functions and classes

The module defines some convenience functions and classes that are used in other modules; they do not make use of gromacs.tools or gromacs.cbook and can be safely imported at any time.

Classes

FileUtils provides functions related to filename handling. It can be used as a base or mixin class. The gromacs.analysis.Simulation class is derived from it.

class gromacs.utilities.FileUtils

Mixin class to provide additional file-related capabilities.

check_file_exists(filename, resolve='exception', force=None)

If a file exists then continue with the action specified in resolve.

resolve must be one of

“ignore”

always return False

“indicate”

return True if it exists

“warn”

indicate and issue a UserWarning

“exception”

raise IOError if it exists

Alternatively, set force for the following behaviour (which ignores resolve):

True

same as resolve = “ignore” (will allow overwriting of files)

False

same as resolve = “exception” (will prevent overwriting of files)

None

ignored, do whatever resolve says

default_extension = None

Default extension for files read/written by this class.

filename(filename=None, ext=None, set_default=False, use_my_ext=False)

Supply a file name for the class object.

Typical uses:

fn = filename()             ---> <default_filename>
fn = filename('name.ext')   ---> 'name'
fn = filename(ext='pickle') ---> <default_filename>'.pickle'
fn = filename('name.inp','pdf') --> 'name.pdf'
fn = filename('foo.pdf',ext='png',use_my_ext=True) --> 'foo.pdf'

The returned filename is stripped of the extension (use_my_ext=False) and if provided, another extension is appended. Chooses a default if no filename is given.

Raises a ValueError exception if no default file name is known.

If set_default=True then the default filename is also set.

use_my_ext=True lets the suffix of a provided filename take priority over a default ext tension.

infix_filename(name, default, infix, ext=None)

Unless name is provided, insert infix before the extension ext of default.

class gromacs.utilities.AttributeDict

A dictionary with pythonic access to keys as attributes — useful for interactive work.

class gromacs.utilities.Timedelta

Extension of datetime.timedelta.

Provides attributes ddays, dhours, dminutes, dseconds to measure the delta in normal time units.

ashours gives the total time in fractional hours.

Functions

Some additional convenience functions that deal with files and directories:

gromacs.utilities.openany(directory[, mode='r'])

Context manager to open a compressed (bzip2, gzip) or plain file (uses anyopen()).

gromacs.utilities.anyopen(datasource, mode='r', **kwargs)

Open datasource (gzipped, bzipped, uncompressed) and return a stream.

Arguments :

datasource

a stream or a filename

mode

'r' opens for reading, 'w' for writing [‘r’]

kwargs

additional keyword arguments that are passed through to the actual handler; if these are not appropriate then an exception will be raised by the handler

gromacs.utilities.realpath(*args)

Join all args and return the real path, rooted at /.

Returns None if any of the args is none.

gromacs.utilities.in_dir(directory[, create=True])

Context manager to execute a code block in a directory.

• The directory is created if it does not exist (unless create = False is set)
• At the end or after an exception code always returns to the directory that was the current directory before entering the block.

gromacs.utilities.find_first(filename, suffices=None)

Find first filename with a suffix from suffices.

Arguments :

filename

base filename; this file name is checked first

suffices

list of suffices that are tried in turn on the root of filename; can contain the ext separator (os.path.extsep) or not

Returns :

The first match or None.

gromacs.utilities.withextsep(extensions)

Return list in which each element is guaranteed to start with os.path.extsep.

Functions that improve list processing and which do not treat strings as lists:

gromacs.utilities.iterable(obj)

Returns True if obj can be iterated over and is not a string.

gromacs.utilities.asiterable(obj)

Returns obj so that it can be iterated over; a string is not treated as iterable

gromacs.utilities.firstof(obj)

Returns the first entry of a sequence or the obj.

Treats strings as single objects.

Functions that help handling Gromacs files:

gromacs.utilities.unlink_f(path)

Unlink path but do not complain if file does not exist.

gromacs.utilities.unlink_gmx(*args)

Unlink (remove) Gromacs file(s) and all corresponding backups.

gromacs.utilities.unlink_gmx_backups(*args)

Unlink (rm) all backup files corresponding to the listed files.

gromacs.utilities.number_pdbs(*args, **kwargs)

Rename pdbs x1.pdb ... x345.pdb –> x0001.pdb ... x0345.pdb

Arguments :

• args: filenames or glob patterns (such as “pdb/md*.pdb”)
• format: format string including keyword num [“%(num)04d”]

Functions that make working with matplotlib easier:

gromacs.utilities.activate_subplot(numPlot)

Make subplot numPlot active on the canvas.

Use this if a simple subplot(numRows, numCols, numPlot) overwrites the subplot instead of activating it.

gromacs.utilities.remove_legend(ax=None)

Remove legend for axes or gca.

See http://osdir.com/ml/python.matplotlib.general/2005-07/msg00285.html

Miscellaneous functions:

gromacs.utilities.convert_aa_code(x)

Converts between 3-letter and 1-letter amino acid codes.

Data

gromacs.utilities.amino_acid_codes = {'A': 'ALA', 'C': 'CYS', 'E': 'GLU', 'D': 'ASP', 'G': 'GLY', 'F': 'PHE', 'I': 'ILE', 'H': 'HIS', 'K': 'LYS', 'M': 'MET', 'L': 'LEU', 'N': 'ASN', 'Q': 'GLN', 'P': 'PRO', 'S': 'SER', 'R': 'ARG', 'T': 'THR', 'W': 'TRP', 'V': 'VAL', 'Y': 'TYR'}

translation table for 1-letter codes –> 3-letter codes .. Note: This does not work for HISB and non-default charge state aa!