gromacs.core – Core functionality

Here the basic command class GromacsCommand is defined. All Gromacs command classes in gromacs.tools are automatically generated from it. The documentation of GromacsCommand applies to all wrapped Gromacs commands should be read by anyone using this package.

class gromacs.core.GromacsCommand(*args, **kwargs)

Base class for wrapping a g_* command.

Limitations: User must have sourced GMXRC so that the python script can inherit the environment and find the gromacs programs.

The class doc string is dynamically replaced by the documentation of the gromacs command when an instance is created.

Set up the command with gromacs flags as keyword arguments.

The following are generic instructions; refer to the Gromacs command usage information that should have appeared before this generic documentation.

As an example, a generic Gromacs command could use the following flags:

cmd = GromacsCommand('v', f=['md1.xtc','md2.xtc'], o='processed.xtc', t=200, ...)

which would correspond to running the command in the shell as

GromacsCommand -v -f md1.xtc md2.xtc -o processed.xtc -t 200

Gromacs command line arguments

Gromacs boolean switches (such as -v) are given as python positional arguments ('v') or as keyword argument (v=True); note the quotes in the first case. Negating a boolean switch can be done with 'nov', nov=True or v=False (and even nov=False works as expected: it is the same as v=True).

Any Gromacs options that take parameters are handled as keyword arguments. If an option takes multiple arguments (such as the multi-file input -f file1 file2 ...) then the list of files must be supplied as a python list.

If a keyword has the python value None then it will not be added to the Gromacs command line; this allows for flexible scripting if it is not known in advance if an input file is needed. In this case the default value of the gromacs tool is used.

Keywords must be legal python keywords or the interpreter raises a SyntaxError but of course Gromacs commandline arguments are not required to be legal python. In this case “quote” the option with an underscore (_) and the underscore will be silently stripped. For instance, -or translates to the illegal keyword or so it must be underscore-quoted:

cmd(...., _or='mindistres.xvg')

Command execution

The command is executed with the run() method or by calling it as a function. The two next lines are equivalent:

cmd(...)
cmd.run(...)

When the command is run one can override options that were given at initialization or one can add additional ones. The same rules for supplying Gromacs flags apply as described above.

Non-Gromacs keyword arguments

The other keyword arguments (listed below) are not passed on to the Gromacs tool but determine how the command class behaves. They are only useful when instantiating a class. This is mostly of interest to developers.

Keywords :

failure

determines how a failure of the gromacs command is treated; it can be one of the following:

‘raise’

raises GromacsError if command fails

‘warn’

issue a GromacsFailureWarning

None

just continue silently

doc : string

additional documentation []

Popen(*args, **kwargs)

Returns a special Popen instance (PopenWithInput).

The instance has its input pre-set so that calls to communicate() will not need to supply input. This is necessary if one wants to chain the output from one command to an input from another.

Todo :Write example.

commandline(*args, **kwargs)

Returns the commandline that run() uses (without pipes).

failuremodes = ('raise', 'warn', None)

Available failure modes.

gmxdoc

Usage for the underlying Gromacs tool (cached).

help(long=False)

Print help; same as using ? in ipython. long=True also gives call signature.

run(*args, **kwargs)

Run the command; args/kwargs are added or replace the ones given to the constructor.

transform_args(*args, **kwargs)

Combine arguments and turn them into gromacs tool arguments.

class gromacs.core.Command(*args, **kwargs)

Wrap simple script or command.

Set up the command class.

The arguments can always be provided as standard positional arguments such as

"-c", "config.conf", "-o", "output.dat", "--repeats=3", "-v", "input.dat"

In addition one can also use keyword arguments such as

c="config.conf", o="output.dat", repeats=3, v=True

These are automatically transformed appropriately according to simple rules:

• Any single-character keywords are assumed to be POSIX-style options and will be prefixed with a single dash and the value separated by a space.
• Any other keyword is assumed to be a GNU-style long option and thus will be prefixed with two dashes and the value will be joined directly with an equals sign and no space.

If this does not work (as for instance for the options of the UNIX find command) then provide options and values in the sequence of positional arguments.

__call__(*args, **kwargs)

Run command with the given arguments:

rc,stdout,stderr = command(*args, input=None, **kwargs)

All positional parameters args and all gromacs kwargs are passed on to the Gromacs command. input and output keywords allow communication with the process via the python subprocess module.

Arguments :

input : string, sequence

to be fed to the process’ standard input; elements of a sequence are concatenated with newlines, including a trailing one [None]

stdin

None or automatically set to PIPE if input given [None]

stdout

how to handle the program’s stdout stream [None]

filehandle

anything that behaves like a file object

None or True

to see output on screen

False or PIPE

returns the output as a string in the stdout parameter

stderr

how to handle the stderr stream [STDOUT]

STDOUT

merges standard error with the standard out stream

False or PIPE

returns the output as a string in the stderr return parameter

None or True

keeps it on stderr (and presumably on screen)

All other kwargs are passed on to the Gromacs tool.

Returns :

The shell return code rc of the command is always returned. Depending on the value of output, various strings are filled with output from the command.

Notes :

By default, the process stdout and stderr are merged.

In order to chain different commands via pipes one must use the special PopenWithInput object (see GromacsCommand.Popen() method) instead of the simple call described here and first construct the pipeline explicitly and then call the PopenWithInput.communicate() method.

STDOUT and PIPE are objects provided by the subprocess module. Any python stream can be provided and manipulated. This allows for chaining of commands. Use

from subprocess import PIPE, STDOUT

when requiring these special streams (and the special boolean switches True/False cannot do what you need.)

(TODO: example for chaining commands)

run(*args, **kwargs)

Run the command; args/kwargs are added or replace the ones given to the constructor.

transform_args(*args, **kwargs)

Transform arguments and return them as a list suitable for Popen.

Popen(*args, **kwargs)

Returns a special Popen instance (PopenWithInput).

The instance has its input pre-set so that calls to communicate() will not need to supply input. This is necessary if one wants to chain the output from one command to an input from another.

Todo :Write example.

help(long=False)

Print help; same as using ? in ipython. long=True also gives call signature.

command_name = None

Derive a class from command; typically one only has to set command_name to the name of the script or executable. The full path is required if it cannot be found by searching PATH.

class gromacs.core.PopenWithInput(*args, **kwargs)

Popen class that knows its input.

1. Set up the instance, including all the input it shoould receive.
2. Call PopenWithInput.communicate() later.

Note

Some versions of python have a bug in the subprocess module ( issue 5179 ) which does not clean up open file descriptors. Eventually code (such as this one) fails with the error:

OSError: [Errno 24] Too many open files

A weak workaround is to increase the available number of open file descriptors with ulimit -n 2048 and run analysis in different scripts.

Initialize with the standard subprocess.Popen arguments.

Keywords :

input

string that is piped into the command

communicate(use_input=True)

Run the command, using the input that was set up on __init__ (for use_input = True)