---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.19.1
  main_language: python
---

```{eval-rst}
.. include:: ../../../global.rst
```

(demo_logging)=
# 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 {download}`demo_logging.py
</../../demos/documented/misc/logging/demo_logging.py>`.


## Setting the log level for terminal output

As briefly touched upon in {ref}`demo_poisson`, the log level for cashocs can be set
with the {py:func}`cashocs.log.set_log_level` as follows

```python
import cashocs

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

As stated previously, there are five log levels available, namely
{py:class}`cashocs.log.DEBUG`, {py:class}`cashocs.log.INFO`,
{py:class}`cashocs.log.WARNING`, {py:class}`cashocs.log.ERROR`, and
{py:class}`cashocs.log.CRITICAL`. The default log level for the terminal output
is {py:class}`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

```python
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

```python
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
{py:func}`cashocs.log.add_logfile` function, which is invoked as follows:

```python
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 {python}`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

```python
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

```python
cashocs.log.remove_timestamps()
```

Finally, you can attach additional handlers for the log with the function
{py:func}`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.