8. Helper modules

The code described here is only relevant for developers.

8.1. mdpow.config – Configuration for MDPOW

The config module provides configurable options for the whole package; eventually it might grow into a more sophisticated configuration system but right now it mostly serves to define which gromacs tools and other scripts are offered in the package and where template files are located. If the user wants to change anything they will still have to do it here in source until a better mechanism with a global configuration file has been implemented.

8.1.1. Force field

By default, MDPOW uses a collection of OPLS/AA force field files based on the Gromacs 4.5.3 distribution, with the following differences:

  • For ions we use the new alkali and halide ion parameters from Table 2 in [Jensen2006] which had shown some small improvements in the paper. They should only be used with the TIP4P water model.
  • OPLS/AA parameters for 1-octanol were added. These parameters were validated against experimental data by computing the density (neat), hydration free energy and logP (the latter being a self consistency check).

The force field files are found in the directory pointed to by the environment variable GMXLIB. By default, mdpow.config sets GMXLIB to includedir unless GMXLIB has already been set. This mechanism allows the user to override the choice of location of force field.

At the moment, only OPLS/AA is tested with MDPOW although in principle it is possible to use other force fields by supplying appropriately customized template files.

References

[Jensen2006]K.P. Jensen and W.L. Jorgensen, J Comp Theor Comput 2 (2006), 1499. doi:10.1021/ct600252r

8.1.2. Location of template files

Template variables list files in the package that can be used as templates such as run input files. Because the package can be a zipped egg we actually have to unwrap these files at this stage but this is completely transparent to the user.

mdpow.config.templates = {'NPT_amber.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/NPT_amber.mdp', 'NPT_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/NPT_charmm.mdp', 'NPT_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/NPT_opls.mdp', 'bar_amber.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/bar_amber.mdp', 'bar_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/bar_charmm.mdp', 'bar_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/bar_opls.mdp', 'em_amber.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/em_amber.mdp', 'em_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/em_charmm.mdp', 'em_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/em_opls.mdp', 'runinput.yml': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/runinput.yml', 'system.top.template': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/system.top.template', 'system_octwet.top.template': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/system_octwet.top.template'}

POW comes with a number of templates for run input files and queuing system scripts. They are provided as a convenience and examples but WITHOUT ANY GUARANTEE FOR CORRECTNESS OR SUITABILITY FOR ANY PURPOSE.

All template filenames are stored in gromacs.config.templates. Templates have to be extracted from the GromacsWrapper python egg file because they are used by external code: find the actual file locations from this variable.

Gromacs mdp templates

These are supplied as examples and there is NO GUARANTEE THAT THEY PRODUCE SENSIBLE OUTPUT — check for yourself! Note that only existing parameter names can be modified with gromacs.cbook.edit_mdp() at the moment; if in doubt add the parameter with its gromacs default value (or empty values) and modify later with edit_mdp().

The safest bet is to use one of the mdout.mdp files produced by gromacs.grompp() as a template as this mdp contains all parameters that are legal in the current version of Gromacs.

mdpow.config.topfiles = {'1cyclo.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1cyclo.gro', '1cyclo.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1cyclo.itp', '1cyclo_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1cyclo_amber.gro', '1cyclo_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1cyclo_charmm.gro', '1oct.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1oct.gro', '1oct.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1oct.itp', '1oct_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1oct_amber.gro', '1oct_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1oct_charmm.gro', '1octnew.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1octnew.itp', '1octwet.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1octwet.gro', '1octwet.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1octwet.itp', '1octwet_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1octwet_amber.gro', '1octwet_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1octwet_charmm.gro', '1octwetnew.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1octwetnew.itp', '1propanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1propanol.itp', '1tol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/1tol.itp', '1tol_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1tol_amber.gro', '1tol_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1tol_charmm.gro', '1tol_oplsaa.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/1tol_oplsaa.gro', 'amber99sb.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/amber99sb.ff', 'aminoacids.c.tdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.c.tdb', 'aminoacids.hdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.hdb', 'aminoacids.n.tdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.n.tdb', 'aminoacids.r2b': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.r2b', 'aminoacids.rtp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.rtp', 'aminoacids.vsd': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/aminoacids.vsd', 'atommass.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/atommass.dat', 'atomname2type.n2t': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/atomname2type.n2t', 'atomtypes.atp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/atomtypes.atp', 'charmm36-mar2019.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/charmm36-mar2019.ff', 'elements.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/elements.dat', 'ethanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/ethanol.itp', 'ffbonded.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/ffbonded.itp', 'ffnonbonded.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/ffnonbonded.itp', 'ffoplsaa.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/ffoplsaa.itp', 'forcefield.doc': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/forcefield.doc', 'forcefield.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/forcefield.itp', 'gbsa.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/gbsa.itp', 'ions.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/ions.itp', 'ions_opls.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/ions_opls.itp', 'm24.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/m24.itp', 'methanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/methanol.itp', 'oplsaa.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff', 'residuetypes.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/residuetypes.dat', 'spc.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/spc.itp', 'spc216.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/spc216.gro', 'spce.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/spce.itp', 'tip3p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/tip3p.itp', 'tip4p.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/tip4p.gro', 'tip4p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/tip4p.itp', 'tip4pd.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/tip4pd.itp', 'tip5p.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/tip5p.gro', 'tip5p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/tip5p.itp', 'vdwradii.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/vdwradii.dat', 'watermodels.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top/oplsaa.ff/watermodels.dat'}

List of all topology files that are included in the package. (includes force field files under top/oplsaa.ff)

mdpow.config.includedir = '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/top'

The package’s include directory for gromacs.grompp(); the environment variable GMXLIB is set to includedir so that the bundled version of the force field is picked up.

mdpow.config.defaults = {'runinput': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/latest/mdpow/templates/runinput.yml'}

Locations of default run input files and configurations.

8.1.3. Functions

The following functions can be used to access configuration data.

mdpow.config.get_template(t)[source]

Find template file t and return its real path.

t can be a single string or a list of strings. A string should be one of

  1. a relative or absolute path,
  2. a filename in the package template directory (defined in the template dictionary gromacs.config.templates) or
  3. a key into templates.

The first match (in this order) is returned. If the argument is a single string then a single string is returned, otherwise a list of strings.

Arguments:t : template file or key (string or list of strings)
Returns:os.path.realpath(t) (or a list thereof)
Raises:ValueError if no file can be located.
mdpow.config.get_templates(t)[source]

Find template file(s) t and return their real paths.

t can be a single string or a list of strings. A string should be one of

  1. a relative or absolute path,
  2. a filename in the package template directory (defined in the template dictionary gromacs.config.templates) or
  3. a key into templates.

The first match (in this order) is returned for each input argument.

Arguments:t : template file or key (string or list of strings)
Returns:list of os.path.realpath(t)
Raises:ValueError if no file can be located.
mdpow.config.get_configuration(filename=None)[source]

Reads and parses a run input config file.

Uses the package-bundled defaults as a basis.

Developer note

Templates have to be extracted from the egg because they are used by external code. All template filenames are stored in config.templates or config.topfiles.

Sub-directories are extracted (see Resource extraction) but the file names themselves will not appear in the template dict. Thus, only store files in subdirectories that don’t have to be explicitly found by the package (e.g. the Gromacs force field files are ok).

mdpow.config._generate_template_dict(dirname)[source]

Generate a list of included top-level files and extract them to a temp space.

Only lists files and directories at the top level of the dirname; however, all directories are extracted recursively and will be available.

8.1.4. Exceptions

exception mdpow.config.NoSectionError[source]

Section entry is missing.

New in version 0.8.0.

class mdpow.config.NoOptionWarning[source]

Warning that an option is missing.

8.2. mdpow.log — Configure logging for POW analysis

Import this module if logging is desired in application code and create the logger in __init__.py:

import log
logger = log.create(logname, logfile)

In modules simply use:

import logging
logger = logging.getLogger(logname)

8.3. mdpow.restart — Restarting and checkpointing

The module provides classes and functions to keep track of which stages of a simulation protocol have been completed. It uses a Journal class for the book-keeping. Together with saving the current state of a protocol to a checkpoint file (using Journalled.save()) it is possible to implement restartable simulation protocols (for example mdpow-equilibrium).

exception mdpow.restart.JournalSequenceError[source]

Raised when a stage is started without another one having been completed.

class mdpow.restart.Journal(stages)[source]

Class that keeps track of the stage in a protocol.

Transaction blocks have to be bracketed by calls to start() and completed(). If a block is started before completion, a JournalSequenceError will be raised.

Other methods such as has_completed() and has_not_completed() can be used to query the status. The attribute incomplete flags the state of the current stage (current).

All completed stages are recorded in the attribute history.

The current (incomplete) stage can be reset to its initial state with Journal.clear().

Example:

J = Journal(['pre', 'main', 'post'])
J.start('pre')
...
J.completed('pre')
J.start('main')
...
# main does not finish properly
print(J.incomplete)
# --> 'main'
J.start('post')
# raises JournalSequenceError

Initialise the journal that keeps track of stages.

Arguments:
stages

list of the stage identifiers, in the order that they should per performed. Stage identifiers are checked against this list before they are accepted as arguments to most methods.

clear()[source]

Reset incomplete status and current stage

completed(stage)[source]

Record completed stage and reset Journal.current

current

Current stage identifier

has_completed(stage)[source]

Returns True if the stage has been started and completed at any time.

has_not_completed(stage)[source]

Returns True if the stage had been started but not completed yet.

history

List of stages completed

incomplete

This last stage was not completed.

start(stage)[source]

Record that stage is starting.

class mdpow.restart.Journalled(*args, **kwargs)[source]

A base class providing methods for journalling and restarts.

It installs an instance of Journal in the attribute Journalled.journal if it does not exist already.

get_protocol(protocol)[source]

Return method for protocol.

  • If protocol is a real method of the class then the method is returned.

  • If protocol is a registered protocol name but no method of the name exists (i.e. protocol is a “dummy protocol”) then a wrapper function is returned. The wrapper has the signature

    dummy_protocol(func, *args, **kwargs)

    Runs func with the arguments and keywords between calls to Journal.start() and Journal.completed(), with the stage set to protocol.

  • Raises a ValueError if the protocol is not registered (i.e. not found in Journalled.protocols).

load(filename=None)[source]

Re-instantiate class from pickled file.

If no filename was supplied then the filename is taken from the attribute filename.

Changed in version 0.7.1: Can read pickle files with either Python 2.7 or 3.x, regardless of the Python version that created the pickle.

protocols = []

Class-attribute that contains the names of computation protocols supported by the class. These are either method names or dummy names, whose logic is provided by an external callback function. The method get_protocol() raises a ValueError if a protocol is not listed in protocols.

save(filename=None)[source]

Save instance to a pickle file.

The default filename is the name of the file that was last loaded from or saved to. Also sets the attribute filename to the absolute path of the saved file.

mdpow.restart.checkpoint(name, sim, filename)[source]

Execute the Journalled.save() method and log the event.

8.4. mdpow.run — Performing complete simulation protocols

The module provides building blocks for complete simulation protocols (or pipelines). Each protocol is written as a function that takes a run input file and the solvent type as input.

The mdpow-* scripts make use of the building blocks.

Typically, journalling is enabled, i.e. the tasks remember which stages have already been completed and can be restarted directly from the last completed stage. (Restarts are only implemeneted at the level of individual steps in a MDPOW protocol, not at the level of continuing interrupted simulations using the Gromacs restart files.)

Input is read from the run input cfg file.

See also

mdpow.restart for the journalling required for restarts.

8.4.1. Protocols

mdpow.run.equilibrium_simulation(cfg, solvent, **kwargs)[source]

Set up and run equilibrium simulation.

See tutorial for the individual steps.

Note

Depending on the settings in the run input file (runlocal), mdrun is executed at various stages, and hence this process can take a while.

mdpow.run.fep_simulation(cfg, solvent, **kwargs)[source]

Set up and run FEP simulation.

See tutorial for the individual steps.

Note

Depending on the settings in the run input file (runlocal), mdrun is executed sequentially for all windows and hence this can take a long time. It is recommended to use runlocal = False in the run input file and submit all window simulations to a cluster.

8.4.2. Support

mdpow.run.setupMD(S, protocol, cfg)[source]

setup MD simulation protocol using the runinput file cfg

mdpow.run.get_mdp_files(cfg, protocols)[source]

Get file names of MDP files from cfg for all protocols

mdpow.run.runMD_or_exit(S, protocol, params, cfg, exit_on_error=True, **kwargs)[source]

run simulation

Can launch mdrun itself (gromacs.run.MDrunner) or exit so that the user can run the simulation independently. Checks if the simulation has completed and sets the return value to True if this is the case.

  • Configuration parameters are taken from the section protocol of the runinput configuration cfg.
  • The directory in which the simulation input files reside can be provided as keyword argument dirname or taken from S.dirs[protocol].
  • The exit_on_error kwarg determines if sys.exit() is called if mdrun fails to complete (True, default) or if instead we raise an gromacs.exceptions.GromacsError (False).
  • Other kwargs are interpreted as options for Mdrun.

Changed in version 0.9.0: New kwarg exit_on_error.