Writing To The Log

Overview

For NTPoly users, it is important to have the option to have NTPoly write calculation information to the log so that they might validate the calculation. We have chosen the YAML output format for NTPoly log files. In this wiki article, we will explain how to use NTPoly's logging module to write YAML files.

YAML

Information about YAML can be found http://www.yaml.org. We choose YAML because it easy for both humans and computers to read. Our expectations is that log data will be mainly read by humans, but having the option to easily parse it with a program can come in handy.

The drawback to using YAML is the need to maintain proper indentation. The next section will go over the features of the Logging Module that help one maintain proper indentation.

Logging Module

When entering into a new routine that one wants to log, the first thing to do is to call the WriteHeader routine and write out a general description of this routine. Next, call the EnterSubLog subroutine to increase the indentation level. When one exits that subroutine, it is necessary to call ExitSubLog to return the indentation level to how it was before.

Two more important subroutines are the WriteElement and WriteListElement subroutines. These allow you to write out a key and value of various types to the log. For citations, there is also the a WriteCitation subroutine that takes in a bibtex key (see the Citations.bib file).

Logging Conventions

Nothing should be written to the log unless an explicit be_verbose flag has been passed to that subroutine. For solvers, there are verbosity settings in the solver parameter modules. This convention is to allow some programs to use NTPoly without interfering with their own logging system.

Logging Example

IF (be_verbose) THEN
  CALL EnterSubLog
  CALL WriteElement(key="Routine", value="log_example")
  CALL WriteElement(key="Times_Printed", value=1)
  CALL ExitSubLog
END IF