9.4. Setting up logging — MDAnalysis.lib.log

Configure logging for MDAnalysis. Import this module if logging is desired in application code.

Logging to a file and the console is set up by default as described under logging to multiple destinations.

The top level logger of the library is named MDAnalysis by convention; a simple logger that writes to the console and logfile can be created with the create() function. This only has to be done once. For convenience, the default MDAnalysis logger can be created with MDAnalysis.start_logging():

import MDAnalysis
MDAnalysis.start_logging()

Once this has been done, MDAnalysis will write messages to the logfile (named MDAnalysis.log by default but this can be changed with the optional argument to start_logging()).

Any code can log to the MDAnalysis logger by using

import logging
logger = logging.getLogger('MDAnalysis.MODULENAME')

# use the logger, for example at info level:
logger.info("Starting task ...")

The important point is that the name of the logger begins with “MDAnalysis.”.

See also

The logging module in the standard library contains in depth documentation about using logging.

9.4.1. Convenience functions

Two convenience functions at the top level make it easy to start and stop the default MDAnalysis logger.

MDAnalysis.start_logging(logfile='MDAnalysis.log', version='0.12.1')[source]

Start logging of messages to file and console.

The default logfile is named MDAnalysis.log and messages are logged with the tag MDAnalysis.

MDAnalysis.stop_logging()[source]

Stop logging to logfile and console.

9.4.2. Other functions and classes for logging purposes

class MDAnalysis.lib.log.NullHandler(level=0)[source]

Silent Handler.

Useful as a default:

h = NullHandler()
logging.getLogger("MDAnalysis").addHandler(h)
del h

see the advice on logging and libraries in http://docs.python.org/library/logging.html?#configuring-logging-for-a-library

Initializes the instance - basically setting the formatter to None and the filter list to empty.

class MDAnalysis.lib.log.ProgressMeter(numsteps, format=None, interval=10, offset=0, quiet=False)[source]

Simple progress meter

Usage:

u = Universe(PSF, DCD)
pm = ProgressMeter(u.trajectory.n_frames, interval=100)
for ts in u.trajectory:
    pm.echo(ts.frame)
    ...

For a trajectory with 10000 frames this will produce output such as

Step   100/10000 [  1.0%]
Step   200/10000 [  2.0%]
...

Because the default format string

"Step %(step)5d/%(numsteps)d [%(percentage)5.1f%%]\r"

ends with a carriage return \r and not a newline \n, the lines will be printed on top of each other.

It is possible to embed (almost) arbitrary additional data in the format string, for example a current RMSD value:

pm = ProgressMeter(u.trajectory.n_frames, interval=100,
“RMSD %(rmsd)5.2f at %(step)5d/%(numsteps)d [%(percentage)5.1f%%]r”)
for ts in u.trajectory:
pm.echo(ts.frame, rmsd=current_rmsd) ...
This will print something like
RMSD 1.02 at 100/10000 [ 1.0%] RMSD 1.89 at 200/10000 [ 2.0%] ...

Set up the ProgressMeter

Parameters:

*numsteps* – total number of steps

Keywords:
interval

only calculate progress every interval steps [10]

format

a format string with Python variable interpolation. Allowed values:

  • step: current step
  • numsteps: total number of steps as supplied in numsteps
  • percentage: percentage of total

The last call to ProgressMeter.print() will automatically issue a newline \n if the last character is the carriage return \r.

If format is None then the default is used. [“Step %(step)5d/%(numsteps)d [%(percentage)5.1f%%]r”]

offset

number to add to step; e.g. if step is 0-based then one would set offset = 1 [0]

quiet

If True, disable all output, False print all messages as specified, [False]

Changed in version 0.8: Keyword argument quiet was added.

echo(step, **kwargs)[source]

Print the state to stderr, but only every interval steps.

  1. calls update()
  2. writes step and percentage to stderr with echo(), using the format string (in ProgressMeter.format)

The last step is always shown, even if not on an interval, and a carriage return is replaced with a new line for a cleaner display.

kwargs are additional attributes that can be references in the format string.

Note

If quiet = True has been set in the constructor or if ProgressMeter.quiet has been set to True the no messages will be printed.

update(step, **kwargs)[source]

Update the state of the ProgressMeter.

kwargs are additional attributes that can be references in the format string.

MDAnalysis.lib.log.clear_handlers(logger)[source]

clean out handlers in the library top level logger

(only important for reload/debug cycles...)

MDAnalysis.lib.log.create(logger_name='MDAnalysis', logfile='MDAnalysis.log')[source]

Create a top level logger.

  • The file logger logs everything (including DEBUG).
  • The console logger only logs INFO and above.

Logging to a file and the console as described under logging to multiple destinations.

The top level logger of MDAnalysis is named MDAnalysis. Note that we are configuring this logger with console output. If a root logger also does this then we will get two output lines to the console.

MDAnalysis.lib.log.echo(s='')[source]

Simple string output that immediately prints to the console.

MDAnalysis.lib.log.start_logging(logfile='MDAnalysis.log', version='0.12.1')[source]

Start logging of messages to file and console.

The default logfile is named MDAnalysis.log and messages are logged with the tag MDAnalysis.

MDAnalysis.lib.log.stop_logging()[source]

Stop logging to logfile and console.