5. Helper modules¶
The code described here is only relevant for developers.
5.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.
5.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 |
5.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/release-0.7.0/mdpow/templates/NPT_amber.mdp', 'NPT_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/NPT_charmm.mdp', 'NPT_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/NPT_opls.mdp', 'bar_amber.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/bar_amber.mdp', 'bar_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/bar_charmm.mdp', 'bar_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/bar_opls.mdp', 'em_amber.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/em_amber.mdp', 'em_charmm.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/em_charmm.mdp', 'em_opls.mdp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/em_opls.mdp', 'runinput.yml': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/runinput.yml', 'system.top': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/system.top', 'system_octwet.top': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/templates/system_octwet.top'}¶ 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 withedit_mdp()
.The safest bet is to use one of the
mdout.mdp
files produced bygromacs.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/release-0.7.0/mdpow/top/1cyclo.gro', '1cyclo.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1cyclo.itp', '1cyclo_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1cyclo_amber.gro', '1cyclo_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1cyclo_charmm.gro', '1oct.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1oct.gro', '1oct.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1oct.itp', '1oct_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1oct_amber.gro', '1oct_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1oct_charmm.gro', '1octnew.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1octnew.itp', '1octwet.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1octwet.gro', '1octwet.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1octwet.itp', '1octwet_amber.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1octwet_amber.gro', '1octwet_charmm.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/1octwet_charmm.gro', '1octwetnew.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1octwetnew.itp', '1propanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/1propanol.itp', 'amber99sb.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/amber99sb.ff', 'aminoacids.c.tdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.c.tdb', 'aminoacids.hdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.hdb', 'aminoacids.n.tdb': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.n.tdb', 'aminoacids.r2b': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.r2b', 'aminoacids.rtp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.rtp', 'aminoacids.vsd': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/aminoacids.vsd', 'atommass.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/atommass.dat', 'atomname2type.n2t': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/atomname2type.n2t', 'atomtypes.atp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/atomtypes.atp', 'charmm36-mar2019.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/charmm36-mar2019.ff', 'elements.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/elements.dat', 'ethanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/ethanol.itp', 'ffbonded.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/ffbonded.itp', 'ffnonbonded.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/ffnonbonded.itp', 'ffoplsaa.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/ffoplsaa.itp', 'forcefield.doc': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/forcefield.doc', 'forcefield.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/forcefield.itp', 'gbsa.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/gbsa.itp', 'ions.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/ions.itp', 'ions_opls.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/ions_opls.itp', 'm24.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/m24.itp', 'methanol.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/methanol.itp', 'oplsaa.ff': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff', 'residuetypes.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/residuetypes.dat', 'spc.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/spc.itp', 'spc216.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/spc216.gro', 'spce.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/spce.itp', 'tip3p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/tip3p.itp', 'tip4p.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/tip4p.gro', 'tip4p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/tip4p.itp', 'tip4pd.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/tip4pd.itp', 'tip5p.gro': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/tip5p.gro', 'tip5p.itp': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/oplsaa.ff/tip5p.itp', 'vdwradii.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/mdpow/top/vdwradii.dat', 'watermodels.dat': '/home/docs/checkouts/readthedocs.org/user_builds/mdpow/checkouts/release-0.7.0/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/release-0.7.0/mdpow/top'¶ The package’s include directory for
gromacs.grompp()
; the environment variableGMXLIB
is set toincludedir
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/release-0.7.0/mdpow/templates/runinput.yml'}¶ Locations of default run input files and configurations.
5.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
- a relative or absolute path,
- a filename in the package template directory (defined in the template dictionary
gromacs.config.templates
) or - 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
- a relative or absolute path,
- a filename in the package template directory (defined in the template dictionary
gromacs.config.templates
) or - 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).
5.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)
5.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()
andcompleted()
. If a block is started before completion, aJournalSequenceError
will be raised.Other methods such as
has_completed()
andhas_not_completed()
can be used to query the status. The attributeincomplete
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.
-
completed
(stage)[source]¶ Record completed stage and reset
Journal.current
-
current
¶ Current stage identifier
-
history
¶ List of stages completed
-
incomplete
¶ This last stage was not completed.
-
class
mdpow.restart.
Journalled
(*args, **kwargs)[source]¶ A base class providing methods for journalling and restarts.
It installs an instance of
Journal
in the attributeJournalled.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()
andJournal.completed()
, with the stage set to protocol.
-
Raises a
ValueError
if the protocol is not registered (i.e. not found inJournalled.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
.
-
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 aValueError
if a protocol is not listed inprotocols
.
-
-
mdpow.restart.
checkpoint
(name, sim, filename)[source]¶ Execute the
Journalled.save()
method and log the event.