pygsti.baseobjs.verbosityprinter

Defines the VerbosityPrinter class, used for logging output.

Module Contents

Classes

VerbosityPrinter

Class responsible for logging things to stdout or a file.

class pygsti.baseobjs.verbosityprinter.VerbosityPrinter(verbosity=1, filename=None, comm=None, warnings=True, split=False, clear_file=True)

Bases: object

Class responsible for logging things to stdout or a file.

Controls verbosity and can print progress bars. ex:

>>> VerbosityPrinter(1)

would construct a printer that printed out messages of level one or higher to the screen.

>>> VerbosityPrinter(3, 'output.txt')

would construct a printer that sends verbose output to a text file

The static function create_printer() will construct a printer from either an integer or an already existing printer. it is a static method of the VerbosityPrinter class, so it is called like so:

>>> VerbosityPrinter.create_printer(2)

or

>>> VerbostityPrinter.create_printer(VerbosityPrinter(3, 'output.txt'))

printer.log('status') would log ‘status’ if the printers verbosity was one or higher. printer.log('status2', 2) would log ‘status2’ if the printer’s verbosity was two or higher

printer.error('something terrible happened') would ALWAYS log ‘something terrible happened’. printer.warning('something worrisome happened') would log if verbosity was one or higher - the same as a normal status.

Both printer.error and printer.warning will prepend ‘ERROR: ‘ or ‘WARNING: ‘ to the message they are given. Optionally, printer.log() can also prepend ‘Status_n’ to the message, where n is the message level.

Logging of progress bars/iterations:

>>> with printer_instance.progress_logging(verbosity):
>>>     for i, item in enumerate(data):
>>>         printer.show_progress(i, len(data))
>>>         printer.log(...)

will output either a progress bar or iteration statuses depending on the printer’s verbosity

Parameters

verbosityint

How verbose the printer should be.

filenamestr, optional

Where to put output (If none, output goes to screen)

commmpi4py.MPI.Comm or ResourceAllocation, optional

Restricts output if the program is running in parallel (By default, if the rank is 0, output is sent to screen, and otherwise sent to commfiles 1, 2, …

warningsbool, optional

Whether or not to print warnings

splitbool, optional

Whether to split output between stdout and stderr as appropriate, or to combine the streams so everything is sent to stdout.

clear_filebool, optional

Whether or not filename should be cleared (overwritten) or simply appended to.

Attributes

_comm_pathstr

relative path where comm files (outputs of non-root ranks) are stored.

_comm_file_namestr

root filename for comm files (outputs of non-root ranks).

_comm_file_extstr

filename extension for comm files (outputs of non-root ranks).

Customize a verbosity printer object

Parameters

verbosityint, optional

How verbose the printer should be.

filenamestr, optional

Where to put output (If none, output goes to screen)

commmpi4py.MPI.Comm or ResourceAllocation, optional

Restricts output if the program is running in parallel (By default, if the rank is 0, output is sent to screen, and otherwise sent to commfiles 1, 2, …

warningsbool, optional

Whether or not to print warnings

clone()

Instead of deepcopy, initialize a new printer object and feed it some select deepcopied members

Returns

VerbosityPrinter

static create_printer(verbosity, comm=None)

Function for converting between interfaces

Parameters

verbosityint or VerbosityPrinter object, required:

object to build a printer from

commmpi4py.MPI.Comm object, optional

Comm object to build printers with. !Will override!

Returns

VerbosityPrinter :

The printer object, constructed from either an integer or another printer

error(message)

Log an error to the screen/file

Parameters

messagestr

the error message

Returns

None

warning(message)

Log a warning to the screen/file if verbosity > 1

Parameters

messagestr

the warning message

Returns

None

log(message, message_level=None, indent_char='  ', show_statustype=False, do_indent=True, indent_offset=0, end='\n', flush=True)

Log a status message to screen/file.

Determines whether the message should be printed based on current verbosity setting, then sends the message to the appropriate output

Parameters

messagestr

the message to print (or log)

message_levelint, optional

the minimum verbosity level at which this level is printed.

indent_charstr, optional

what constitutes an “indent” (messages at higher levels are indented more when do_indent=True).

show_statustypebool, optional

if True, prepend lines with “Status Level X” indicating the message_level.

do_indentbool, optional

whether messages at higher message levels should be indented. Note that if this is False it may be helpful to set show_statustype=True.

indent_offsetint, optional

an additional number of indentations to add, on top of any due to the message level.

endstr, optional

the character (or string) to end message lines with.

flushbool, optional

whether stdout should be flushed right after this message is printed (this avoids delays in on-screen output due to buffering).

Returns

None

verbosity_env(level)

Create a temporary environment with a different verbosity level.

This is context manager, controlled using Python’s with statement:

>>> with printer.verbosity_env(2):
        printer.log('Message1') # printed at verbosity level 2
        printer.log('Message2') # printed at verbosity level 2

Parameters

levelint

the verbosity level of the environment.

progress_logging(message_level=1)

Context manager for logging progress bars/iterations.

(The printer will return to its normal, unrestricted state when the progress logging has finished)

Parameters

message_levelint, optional

progress messages will not be shown until the verbosity level reaches message_level.

show_progress(iteration, total, bar_length=50, num_decimals=2, fill_char='#', empty_char='-', prefix='Progress:', suffix='', verbose_messages=None, indent_char='  ', end='\n')

Displays a progress message (to be used within a progress_logging block).

Parameters

iterationint

the 0-based current iteration – the interation number this message is for.

totalint

the total number of iterations expected.

bar_lengthint, optional

the length, in characters, of a text-format progress bar (only used when the verbosity level is exactly equal to the progress_logging message level.

num_decimalsint, optional

number of places after the decimal point that are displayed in progress bar’s percentage complete.

fill_charstr, optional

replaces ‘#’ as the bar-filling character

empty_charstr, optional

replaces ‘-’ as the empty-bar character

prefixstr, optional

message in front of the bar

suffixstr, optional

message after the bar

verbose_messageslist, optional

A list of strings to display after an initial “Iter X of Y” line when the verbosity level is higher than the progress_logging message level and so more verbose messages are shown (and a progress bar is not). The elements of verbose_messages will occur, one per line, after the initial “Iter X of Y” line.

indent_charstr, optional

what constitutes an “indentation”.

endstr, optional

the character (or string) to end message lines with.

Returns

None

start_recording()

Begins recording the output (to memory).

Begins recording (in memory) a list of (type, verbosityLevel, message) tuples that is returned by the next call to stop_recording().

Returns

None

is_recording()

Returns whether this VerbosityPrinter is currently recording.

Returns

bool

stop_recording()

Stops recording and returns recorded output.

Stops a “recording” started by start_recording() and returns the list of (type, verbosityLevel, message) tuples that have been recorded since then.

Returns

list