### Navigation

- index
- modules |
- next |
- previous |
- MDAnalysis 0.7.7 documentation »
- 7. Core modules »

# 7.10. Setting up logging — `MDAnalysis.core.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.

## 7.10.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')

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

  Stop logging to logfile and console.

## 7.10.2. Other functions and classes for logging purposes

class `MDAnalysis.core.log.``NullHandler`(level=0)

  Silent Handler.

  Useful as a default:

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

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

class `MDAnalysis.core.log.``ProgressMeter`(numsteps, format=None, interval=10, offset=0)

  Simple progress meter

  Usage:

      u = Universe(PSF, DCD)
      pm = ProgressMeter(u.trajectory.numframes, 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.numframes, 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

  Arguments : | 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]

  `echo`(step, **kwargs)

    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.

  `update`(step, **kwargs)

    Update the state of the ProgressMeter.

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

`MDAnalysis.core.log.``clear_handlers`(logger)

  clean out handlers in the library top level logger

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

`MDAnalysis.core.log.``create`(logger_name='MDAnalysis', logfile='MDAnalysis.log')

  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.core.log.``echo`(s='')

  Simple string output that immediately prints to the console.

### Navigation

- index
- modules |
- next |
- previous |
- MDAnalysis 0.7.7 documentation »
- 7. Core modules »