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
- 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')
Open datasource (gzipped, bzipped, uncompressed) and return a stream.
- datasource: a file or a stream
- mode: ‘r’ or ‘w’
-
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
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
- translation table for 1-letter codes –> 3-letter codes
.. Note: This does not work for HISB and non-default charge state aa!