armi.runLog module

This module handles logging of console during a simulation.

The default way of calling and the global armi logger is to just import it:

from armi import runLog

You may want a logger specific to a single module, say to provide debug logging for only one module. That functionality is provided by a global override of logging imports:

import logging
runLog = logging.getLogger(__name__)

In either case, you can then log things the same way:

runLog.info('information here')
runLog.error('extra error info here')
raise SomeException  # runLog.error() implies that the code will crash!

Or change the log level the same way:

runLog.setVerbosity('debug')

armi.runLog.close(mpiRank=None)

End use of the log. Concatenate if needed and restore defaults.

armi.runLog.concatenateLogs(logDir=None)

Concatenate the armi run logs and delete them.

Should only ever be called by parent.

Implementation: Log files from different processes are combined. I_ARMI_LOG_MPI

signature: concatenateLogs requirements: R_ARMI_LOG_MPI

The log files are plain text files. Since ARMI is frequently run in parallel, the situation arises where each ARMI process generates its own plain text log file. This function combines the separate log files, per process, into one log file. The files are written in numerical order, with the lead process stdout first then the lead process stderr. Then each other process is written to the combined file, in order, stdout then stderr. Finally, the original stdout and stderr files are deleted.

armi.runLog.raw(msg)

Print raw text without any special functionality.

armi.runLog.extra(msg, single=False, label=None)

armi.runLog.debug(msg, single=False, label=None)

armi.runLog.info(msg, single=False, label=None)

armi.runLog.important(msg, single=False, label=None)

armi.runLog.warning(msg, single=False, label=None)

armi.runLog.error(msg, single=False, label=None)

armi.runLog.header(msg, single=False, label=None)

armi.runLog.warningReport()

armi.runLog.setVerbosity(level)

armi.runLog.getVerbosity()

class armi.runLog.DeduplicationFilter(*args, **kwargs)

Bases: Filter

Important logging filter.

• allow users to turn off duplicate warnings

• handles special indentation rules for our logs

filter(record)

class armi.runLog.RunLogger(*args, **kwargs)

Bases: Logger

Custom Logger to support our specific desires.

1. Giving users the option to de-duplicate warnings

2. Piping stderr to a log file

Implementation: A simulation-wide log, with user-specified verbosity. I_ARMI_LOG

signature: RunLogger requirements: R_ARMI_LOG

Log statements are any text a user wants to record during a run. For instance, basic notifications of what is happening in the run, simple warnings, or hard errors. Every log message has an associated log level, controlled by the “verbosity” of the logging statement in the code. In the ARMI codebase, you can see many examples of logging: runLog.error("This sort of error might usually terminate the run.") runLog.warning("Users probably want to know.") runLog.info("This is the usual verbosity.") runLog.debug("This is only logged during a debug run.") The full list of logging levels is defined in _RunLog.getLogLevels(), and the developer specifies the verbosity of a run via _RunLog.setVerbosity(). At the end of the ARMI-based simulation, the analyst will have a full record of potentially interesting information they can use to understand their run.

Implementation: Logging is done to the screen and to file. I_ARMI_LOG_IO

signature: RunLogger requirements: R_ARMI_LOG_IO

This logger makes it easy for users to add log statements to and ARMI application, and ARMI will control the flow of those log statements. In particular, ARMI overrides the normal Python logging tooling, to allow developers to pipe their log statements to both screen and file. This works for stdout and stderr. At any place in the ARMI application, developers can interject a plain text logging message, and when that code is hit during an ARMI simulation, the text will be piped to screen and a log file. By default, the logging module only logs to screen, but ARMI adds a FileHandler in the RunLog constructor and in _RunLog.startLog.

FMT = '%(levelname)s%(message)s'

log(msgType, msg, single=False, label=None, *args, **kwargs)

This is a wrapper around logger.log() that does most of the work.

This is used by all message passers (e.g. info, warning, etc.). In this situation, we do the mangling needed to get the log level to the correct number. And we do some custom string manipulation so we can handle de-duplicating warnings.

allowStopDuplicates()

Helper method to allow us to safely add the deduplication filter at any time.

write(msg, **kwargs)

The redirect method that allows to do stderr piping.

flush(*args, **kwargs)

Stub, purely to allow stderr piping.

close()

Helper method, to shutdown and delete a Logger.

getDuplicatesFilter()

This object should have a no-duplicates filter. If it exists, find it.

warningReport()

Summarize all warnings for the run.

setVerbosity(intLevel)

A helper method to try to partially support the local, historical method of the same name.

class armi.runLog.NullLogger(name, isStderr=False)

Bases: RunLogger

This is really just a placeholder for logging before or after the span of a normal armi run.

It will forward all logging to stdout/stderr, as you’d normally expect. But it will preserve the formatting and duplication tools of the armi library.

addHandler(*args, **kwargs)

Ensure this STAYS a null logger.

armi.runLog.createLogDir(logDir: str = None) → None

A helper method to create the log directory.

armi.runLog.logFactory()

Create the default logging object.