1.6. Status and Error Logging

Added in version 6.2.0.

SUNDIALS includes a built-in logging functionality which can be used to direct error messages, warning messages, informational output, and debugging output to specified files. This capability requires enabling both build-time and run-time options to ensure the best possible performance is achieved.

1.6.1. Enabling Logging

To enable logging, the CMake option SUNDIALS_LOGGING_LEVEL must be set to the maximum desired output level when configuring SUNDIALS. See the SUNDIALS_LOGGING_LEVEL documentation for the numeric values corresponding to errors, warnings, info output, and debug output where errors < warnings < info output < debug output < extra debug output. By default only warning and error messages are logged.

When SUNDIALS is built with logging enabled, then the default logger (stored in the SUNContext object) may be configured through environment variables without any changes to user code. The available environment variables are:

SUNLOGGER_ERROR_FILENAME
SUNLOGGER_WARNING_FILENAME
SUNLOGGER_INFO_FILENAME
SUNLOGGER_DEBUG_FILENAME

These environment variables may be set to a filename string. There are two special filenames: stdout and stderr. These two filenames will result in output going to the standard output file and standard error file. For example, consider the CVODE Roberts example, where we can direct the informational output to the file sun.log as follows

SUNLOGGER_INFO_FILENAME=sun.log ./examples/cvode/serial/cvRoberts_dns

The different environment variables may all be set to the same file, or to distinct files, or some combination there of. To disable output for one of the streams, then do not set the environment variable, or set it to an empty string. If SUNDIALS_LOGGING_LEVEL was set at build-time to a level lower than the corresponding environment variable, then setting the environment variable will do nothing. For example, if the logging level is set to 2 (errors and warnings), setting SUNLOGGER_INFO_FILENAME will do nothing.

Alternatively, the default logger can be accessed with SUNContext_GetLogger() and configured using the Logger API or a user may create, configure, and attach a non-default logger using the Logger API.

Warning

A non-default logger should be created and attached to the context object prior to any other SUNDIALS calls in order to capture all log events.

The following examples demonstrate how to use the logging interface via the C API:

examples/arkode/CXX_serial/ark_analytic_sys.cpp
examples/cvode/serial/cvAdvDiff_bnd.c
examples/cvode/parallel/cvAdvDiff_diag_p.c
examples/kinsol/CXX_parallel/kin_em_p.cpp
examples/kinsol/CUDA_mpi/kin_em_mpicuda.cpp

1.6.2. Logging Output

Error or warning logs are a single line output with an error or warning message of the form

[level][rank][scope][label] message describing the error or warning

where the values in brackets have the following meaning:

  • level is the log level of the message and will be ERROR, WARNING, INFO, or DEBUG

  • rank is the MPI rank the message was written from (0 by default or if SUNDIALS was built without MPI enabled)

  • scope is the message scope i.e., the name of the function from which the message was written

  • label provides additional context or information about the logging output e.g., begin-step, end-linear-solve, etc.

Informational or debugging logs are either a single line output with a comma-separated list of key-value pairs of the form

[level][rank][scope][label] key1 = value1, key2 = value2

or multiline output with one value per line for keys corresponding to a vector or array e.g.,

[level][rank][scope][label] y(:) =
y[0]
y[1]
...

Note

When extra debugging output is enabled, the output will include vector values (so long as the N_Vector used supports printing). Depending on the problem size, this may result in very large logging files.

1.6.3. Logging Tools

Added in version 7.2.0.

To assist with extracting data from logging output files, the tools directory contains the suntools Python module which provides utilities for parsing log files in the logs sub-module.

logs.log_file_to_list(filename)

Parses a log file and returns a list of dictionaries.

Parameters:

filename (str) – The name of the log file to parse.

Returns:

A list of dictionaries.

The list returned for a time integrator log file will contain a dictionary for each step attempt e.g.,

[ {step : 1, tn : 0.0, h : 0.01, ...}, {step : 2, tn : 0.01, h : 0.10, ...}, ...]
logs.print_log(log, indent=0)

Print a log file list created by log_file_to_list().

Parameters:

  • log (list) – The log file list to print.

  • indent (int) – The number of spaces to indent the output.

logs.get_history(log, key, step_status=None, time_range=None, step_range=None, group_by_level=False)

Extract the history of a key from a log file list created by log_file_to_list().

Parameters:

  • log (list) – The log file list to extract values from.

  • key (str) – The key to extract.

  • step_status (str) – Only extract values for steps which match the given status e.g., “success” or “failed”.

  • time_range ([float, float]) – Only extract values in the time interval, [low, high].

  • step_range ([int, int]) – Only extract values in the step number interval, [low, high].

  • group_by_level (bool) – Group outputs by time level.

Returns:

A list of steps, times, and values

The tools directory also contains example scripts demonstrating how to use the log parsing functions to extract and plot data.

  • log_example_print.py – parses a log file and prints the log file list.

  • log_example.py – plots the step size, order, or error estimate history from an ARKODE, CVODE(S), or IDA(S) log file.

  • log_example_mri.py – plots the step size history from an ARKODE MRIStep log file.

For more details on using an example script, run the script with the --help flag.

1.6.4. Logger API

The central piece of the Logger API is the SUNLogger type:

type SUNLogger

An opaque pointer containing logging information.

When SUNDIALS is built with logging enabled, a default logging object is stored in the SUNContext object and can be accessed with a call to SUNContext_GetLogger().

The enumerated type SUNLogLevel is used by some of the logging functions to identify the output level or file.

enum SUNLogLevel

The SUNDIALS logging level

enumerator SUN_LOGLEVEL_ALL

Represents all output levels

enumerator SUN_LOGLEVEL_NONE

Represents none of the output levels

enumerator SUN_LOGLEVEL_ERROR

Represents error-level logging messages

enumerator SUN_LOGLEVEL_WARNING

Represents warning-level logging messages

enumerator SUN_LOGLEVEL_INFO

Represents info-level logging messages

enumerator SUN_LOGLEVEL_DEBUG

Represents deubg-level logging messages

The SUNLogger class provides the following methods.

int SUNLogger_Create(SUNComm comm, int output_rank, SUNLogger *logger)

Creates a new SUNLogger object.

Arguments:

  • comm – the MPI communicator to use, if MPI is enabled, otherwise can be SUN_COMM_NULL.

  • output_rank – the MPI rank used for output (can be -1 to print to all ranks).

  • logger – [in,out] On input this is a pointer to a SUNLogger, on output it will point to a new SUNLogger instance.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_CreateFromEnv(SUNComm comm, SUNLogger *logger)

Creates a new SUNLogger object and opens the output streams/files from the environment variables:

SUNLOGGER_ERROR_FILENAME
SUNLOGGER_WARNING_FILENAME
SUNLOGGER_INFO_FILENAME
SUNLOGGER_DEBUG_FILENAME
Arguments:

  • comm – the MPI communicator to use, if MPI is enabled, otherwise can be SUN_COMM_NULL.

  • logger – [in,out] On input this is a pointer to a SUNLogger, on output it will point to a new SUNLogger instance.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_SetErrorFilename(SUNLogger logger, const char *error_filename)

Sets the filename for error output.

Arguments:

  • logger – a SUNLogger object.

  • error_filename – the name of the file to use for error output.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_SetWarningFilename(SUNLogger logger, const char *warning_filename)

Sets the filename for warning output.

Arguments:

  • logger – a SUNLogger object.

  • warning_filename – the name of the file to use for warning output.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_SetInfoFilename(SUNLogger logger, const char *info_filename)

Sets the filename for info output.

Arguments:

  • logger – a SUNLogger object.

  • info_filename – the name of the file to use for info output.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_SetDebugFilename(SUNLogger logger, const char *debug_filename)

Sets the filename for debug output.

Arguments:

  • logger – a SUNLogger object.

  • debug_filename – the name of the file to use for debug output.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_QueueMsg(SUNLogger logger, SUNLogLevel lvl, const char *scope, const char *label, const char *msg_txt, ...)

Queues a message to the output log level.

Arguments:

  • logger – a SUNLogger object.

  • lvl – the message log level (i.e. error, warning, info, debug).

  • scope – the message scope (e.g. the function name).

  • label – the message label.

  • msg_txt – the message text itself.

  • ... – the format string arguments

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_Flush(SUNLogger logger, SUNLogLevel lvl)

Flush the message queue(s).

Arguments:

  • logger – a SUNLogger object.

  • lvl – the message log level (i.e. error, warning, info, debug or all).

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_GetOutputRank(SUNLogger logger, int *output_rank)

Get the output MPI rank for the logger.

Arguments:

  • logger – a SUNLogger object.

  • output_rank – [in,out] On input this is a pointer to an int, on output it points to the int holding the output rank.

Returns:

  • Returns zero if successful, or non-zero if an error occurred.

int SUNLogger_Destroy(SUNLogger *logger)

Free the memory for the SUNLogger object.

Arguments:

  • logger – a pointer to the SUNLogger object.

Returns:

  • Returns zero if successful, or non-zero if an error occur.