Logging with cashocs

Topic

In this demo, we investigate how cashocs logging behavior can be configured. Cashocs uses the python built-in logging library for logging and has the level INFO as default log level for its terminal output. This ensures that users can easily see the most important parts down to the solution of the PDEs readily in the terminal when running script. However, for some users, this might be too cluttered, while others would like to have additional information, particularly for debugging purposes. These objectives can be readily achieved and in the following, we will discuss how.

Implementation

The complete python code can be found in the file demo_logging.py.

Setting the log level for terminal output

As briefly touched upon in Distributed Control of a Poisson Problem, the log level for cashocs can be set with the cashocs.log.set_log_level() as follows

import cashocs

cashocs.log.set_log_level(cashocs.log.INFO)

As stated previously, there are five log levels available, namely cashocs.log.DEBUG, cashocs.log.INFO, cashocs.log.WARNING, cashocs.log.ERROR, and cashocs.log.CRITICAL. The default log level for the terminal output is cashocs.log.INFO, which will print information, which is relevant for most users, such as the progress of the optimization or details regarding the solution of the (nonlinear) state equation. If this is too much information for you, then you can restrict the terminal logs to warnings and higher with a call to

cashocs.log.set_log_level(cashocs.log.WARNING)

which will print way less details. On the other hand, much more details can be found when using

cashocs.log.set_log_level(cashocs.log.DEBUG)

which will provide detailed information regarding most operations cashocs performs. For a detailed introduction to the pythons logging library and the associated log levels, we refer the reader to https://docs.python.org/3/library/logging.html.

As the output in the console might be hard to read, analyze or keep, cashocs offers the possibility to also log to various log files with the help of the cashocs.log.add_logfile() function, which is invoked as follows:

cashocs.log.add_logfile("output.log", mode="a", level=cashocs.log.DEBUG)

This creates a new file named output.log which will be appended to if it is used multiple times, and which has a possibly different log level than the default terminal logger. This function can be called multiple times to define various log files. Alternatively, the mode mode="w" can be used to overwrite the log file if it exists.

Additionally, cashocs offers the possibility to add timestamps to the logs. These can be added with the command

cashocs.log.add_timestamps()

so that you can see when an event was logged. If you have turned this on (it is disabled by default), the timestamps can be removed with a call to

cashocs.log.remove_timestamps()

Finally, you can attach additional handlers for the log with the function cashocs.log.add_handler(). For this, you can just pass any valid handler (see https://docs.python.org/3/library/logging.html#handler-objects) and cashocs will also log to this handler.