6. Helper modules

The code described here is only relevant for developers.

6.1. 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)

6.2. 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

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

class mdpow.restart.Journal(stages)

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()

Reset incomplete status and current stage

completed(stage)

Record completed stage and reset Journal.current

property current

Current stage identifier

has_completed(stage)

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

has_not_completed(stage)

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

This is subtly different from not has_completed() in that two things have to be true:

1. No stage is active (which is the case when a restart is attempted).

2. The stage has not been completed previously (i.e., has_completed() returns False)

property history

List of stages completed

property incomplete

This last stage was not completed.

start(stage)

Record that stage is starting.

class mdpow.restart.Journalled(*args, **kwargs)

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)

Return method for protocol.

• If protocol is a real method of the class then the method is returned. This method should implement its own use of Journal.start() and Journal.completed().

• 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.

  The function should return True on success and False on failure.

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

load(filename=None)

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)

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)

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