Logging cookbook¶

The Atomica logger is named 'atomica'. Typically, the logger is accessed via

import atomica
logger = atomica.logger

Loggers are stored globally by name, so you can alternatively retrieve the logger from anywhere using

import logging
logger = logging.getLogger('atomica')

Changing the amount of output¶

Once you have the logger object (e.g. in your own script) you can change the logging level to control the amount of output displayed. The most common levels are

Level	Command
Show warnings or worse only	`logger.setLevel('WARNING')`
Default - Show normal output	`logger.setLevel('INFO')`
Show extra detailed output	`logger.setLevel('DEBUG')`

When writing code for Atomica, set the level of the message accordingly e.g. in the code you are writing, use

logger.warning('This should be displayed as a warning')
logger.info('This is information that the user will normally see')
logger.debug('This is extra-verbose output')

Note that the use of logger.debug means that you do not need to set verbose flags and if statements - instead, just set the logging level to debug.

Note also that the default logging level is set in atomica/__init__.py so normally you should set the logging level in your script after importing Atomica e.g.

import atomica as at
at.logger.setLevel('DEBUG')

Dumping output to a log file¶

A common task is storing the log messages for a simulation run. This can be accomplished easily using the at.start_logging function:

import atomica as at
at.start_logging('logfile.txt')

This will automatically create the log file, and prepend version information (normally not printed). Log messages replicate the messages printed by Atomica. The traceback for any unhandled errors that occur will also be logged. The log messages are gated by the logger level in Atomica, so the verbosity can be changed by using at.logger.setLevel.

The key items that will NOT be captured in the file log are

Output generated by a print statement. Instead of using print, use at.logger.info('message') which will both print and log the output
Output generated by worker processes e.g. if using run_sampled_sims(parallel=True)

You can stop logging and close the file by using

at.stop_logging()

The optional reset argument to at.start_logging() allows you to close any existing file loggers, and clear any existing log file with the requested filename. For instance,

at.start_logging('logfile.txt', reset=True)

is equivalent to

at.stop_logging()
at.start_logging('logfile.txt')

such that any existing file logs will be closed, and if logfile.txt already exists, it will be cleared. Otherwise, if a file logger has already been created, starting logging will have no effect. For example,

at.start_logging('logfile.txt')
at.start_logging('logfile2.txt')

The second command will not have any effect and only logfile.txt will be created.