pygsti.baseobjs.verbosityprinter.VerbosityPrinter

pygsti.baseobjs.verbosityprinter.VerbosityPrinter#

class 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:

verbosity (int) – How verbose the printer should be.
filename (str, optional) – Where to put output (If none, output goes to screen)
comm (mpi4py.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, …
warnings (bool, optional) – Whether or not to print warnings
split (bool, optional) – Whether to split output between stdout and stderr as appropriate, or to combine the streams so everything is sent to stdout.
clear_file (bool, optional) – Whether or not filename should be cleared (overwritten) or simply appended to.

_comm_path#

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

Type:: str

_comm_file_name#

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

Type:: str

_comm_file_ext#

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

Type:: str

Customize a verbosity printer object

Parameters:

verbosity (int, optional) – How verbose the printer should be.
filename (str, optional) – Where to put output (If none, output goes to screen)
comm (mpi4py.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, …
warnings (bool, optional) – Whether or not to print warnings

Methods

`__init__`([verbosity, filename, comm, ...])	Customize a verbosity printer object
`clone`()	Instead of deepcopy, initialize a new printer object and feed it some select deepcopied members
`create_printer`(verbosity[, comm])	Function for converting between interfaces
`error`(message)	Log an error to the screen/file
`is_recording`()	Returns whether this VerbosityPrinter is currently recording.
`log`(message[, message_level, indent_char, ...])	Log a status message to screen/file.
`progress_logging`([message_level])	Context manager for logging progress bars/iterations.
`show_progress`(iteration, total[, ...])	Displays a progress message (to be used within a progress_logging block).
`start_recording`()	Begins recording the output (to memory).
`stop_recording`()	Stops recording and returns recorded output.
`verbosity_env`(level)	Create a temporary environment with a different verbosity level.
`warning`(message[, message_level, ...])	Log a warning to the screen/file if verbosity > 1

clone()#

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

Return type:: VerbosityPrinter

static create_printer(verbosity, comm=None)#

Function for converting between interfaces

Parameters:

verbosity (int or VerbosityPrinter object, required:) – object to build a printer from
comm (mpi4py.MPI.Comm object, optional) – Comm object to build printers with. !Will override!

Returns:

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

Return type:

VerbosityPrinter

error(message)#

Log an error to the screen/file

Parameters:: message (str) – the error message
Return type:: None

is_recording()#

Returns whether this VerbosityPrinter is currently recording.

Return type:: bool

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:

message (str) – the message to print (or log)
message_level (int, optional) – the minimum verbosity level at which this level is printed.
indent_char (str, optional) – what constitutes an “indent” (messages at higher levels are indented more when do_indent=True).
show_statustype (bool, optional) – if True, prepend lines with “Status Level X” indicating the message_level.
do_indent (bool, 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_offset (int, optional) – an additional number of indentations to add, on top of any due to the message level.
end (str, optional) – the character (or string) to end message lines with.
flush (bool, optional) – whether stdout should be flushed right after this message is printed (this avoids delays in on-screen output due to buffering).

Return type:

None

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_level (int, 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:

iteration (int) – the 0-based current iteration – the iteration number this message is for.
total (int) – the total number of iterations expected.
bar_length (int, 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_decimals (int, optional) – number of places after the decimal point that are displayed in progress bar’s percentage complete.
fill_char (str, optional) – replaces ‘#’ as the bar-filling character
empty_char (str, optional) – replaces ‘-’ as the empty-bar character
prefix (str, optional) – message in front of the bar
suffix (str, optional) – message after the bar
verbose_messages (list, 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_char (str, optional) – what constitutes an “indentation”.
end (str, optional) – the character (or string) to end message lines with.

Return type:

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

Return type:: None

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.

Return type:: list

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:: level (int) – the verbosity level of the environment.

warning(message, message_level=None, indent_char=' ', do_indent=True, indent_offset=0)#

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

Parameters:: message (str) – the warning message
Return type:: None

pygsti.baseobjs.verbosityprinter.VerbosityPrinter

Contents

pygsti.baseobjs.verbosityprinter.VerbosityPrinter#