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, set the environment variable to an empty string. To leave the stream at its default output, do not set the environment variable. 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)

Parse a log file and return as a Python list of dictionaries.

This is the core parsing function that converts SUNDIALS log files into Python data structures. Use this function when you need to work with the data directly in Python (analysis, filtering, custom processing).

Parameters:

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

Returns:

A list of dictionaries, one per step attempt.

Return type:

list

The list returned for a time integrator log file will contain a dictionary for each step attempt:

[
  {
    "step": 1,
    "tn": 0.0,
    "h": 0.01,
    "status": "success",
    "dsm": 2.6e-13,
    "level": 0,
    "stages": [
      {"stage": 0, "implicit": 0, "tcur": 0.0, "status": "success"},
      {"stage": 1, "implicit": 0, "tcur": 0.001, "status": "success"},
      ...
    ],
    "compute-solution": {
      "mass type": 0,
      "status": "success"
    }
  },
  {
    "step": 2,
    "tn": 0.01,
    "h": 0.02,
    ...
  },
  ...
]

Example usage:

from suntools import logs
import matplotlib.pyplot as plt

# Parse the log file
data = logs.log_file_to_list("sun.log")

# Extract lists of passed and failed step data
passed = [s for s in data if "success" in s["status"]]
failed = [s for s in data if "failed" in s["status"]]

print("Steps stats: ")
print(f"  Attempted:  {len(data)}")
print(f"  Successful: {len(passed)}")
print(f"  Failed:     {len(failed)}")
print(f"  Min Step:   {min(s["h"] for s in passed)}")
print(f"  Max Step:   {max(s["h"] for s in passed)}")
print(f"  Avg Step:   {sum(s["h"] for s in passed) / len(passed)}")

# Plot step size history
s_steps, s_times, s_steps = logs.get_history(passed, "h")
f_steps, f_times, f_steps = logs.get_history(failed, "h")

fig, ax = plt.subplots()
ax.plot(s_times, s_steps, color="b", marker=".", label="passed")
ax.scatter(f_times, f_steps, color="r", marker="x", label="failed")
ax.legend(loc="best")
ax.set(xlabel="time", ylabel="step size", title="Step Size History")
plt.show()

logs.print_log(log, indent=2)

Print a log file list as formatted JSON.

This function takes parsed log data and prints it in a human-readable JSON format. Useful for debugging and quick inspection.

Parameters:

• log (list) – The log file list from log_file_to_list().

• indent (int) – The number of spaces to indent the JSON output (default: 2).

Example usage:

from suntools import logs

# Parse the log file
data = logs.log_file_to_list("sun.log")

# Print just the first few steps
logs.print_log(data[:5])

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 following function pointer types are used to define custom message queueing and flushing behavior:

typedef SUNErrCode (*SUNLoggerQueueMsgFn)(SUNLogger logger, SUNLogLevel lvl, const char *prefix, int rank, const char *scope, const char *label, const char *payload, void *content)

Function pointer type for custom message queueing implementations.

Arguments:

• logger – the SUNLogger object

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

• prefix – the string representation of the log level (e.g., “ERROR”, “WARNING”)

• rank – the MPI rank of the caller

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

• label – the message label

• payload – the formatted message text

• content – user-defined data pointer (passed via SUNLogger_SetQueueAndFlushMsgFns())

Returns:

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

typedef SUNErrCode (*SUNLoggerFlushMsgFn)(SUNLogger logger, SUNLogLevel lvl, void *content)

Function pointer type for custom message flushing implementations.

Arguments:

• logger – the SUNLogger object.

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

• content – user-defined data pointer (passed via SUNLogger_SetQueueAndFlushMsgFns()).

Returns:

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

The SUNLogger class provides the following methods.

SUNErrCode 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.

SUNErrCode 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.

SUNErrCode 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. Passing NULL or an empty string disables output for this stream.

Returns:

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

SUNErrCode SUNLogger_SetErrorFile(SUNLogger logger, FILE *error_fp)

Sets the file pointer for error output.

The logger does not take ownership of error_fp; the user is responsible for closing the file if needed. Passing NULL disables output for this stream.

Arguments:

• logger – a SUNLogger object.

• error_fp – the FILE pointer to use for error output.

Returns:

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

SUNErrCode SUNLogger_GetErrorFile(SUNLogger logger, FILE **error_fp)

Gets the file pointer for error output.

Arguments:

• logger – a SUNLogger object.

• error_fp – on output, the file pointer used for error output.

Returns:

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

SUNErrCode 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. Passing NULL or an empty string disables output for this stream.

Returns:

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

SUNErrCode SUNLogger_SetWarningFile(SUNLogger logger, FILE *warning_fp)

Sets the file pointer for warning output.

The logger does not take ownership of warning_fp; the user is responsible for closing the file if needed. Passing NULL disables output for this stream.

Arguments:

• logger – a SUNLogger object.

• warning_fp – the FILE pointer to use for warning output.

Returns:

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

SUNErrCode SUNLogger_GetWarningFile(SUNLogger logger, FILE **warning_fp)

Gets the file pointer for warning output.

Arguments:

• logger – a SUNLogger object.

• warning_fp – on output, the file pointer used for warning output.

Returns:

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

SUNErrCode 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. Passing NULL or an empty string disables output for this stream.

Returns:

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

SUNErrCode SUNLogger_SetInfoFile(SUNLogger logger, FILE *info_fp)

Sets the file pointer for info output.

The logger does not take ownership of info_fp; the user is responsible for closing the file if needed. Passing NULL disables output for this stream.

Arguments:

• logger – a SUNLogger object.

• info_fp – the FILE pointer to use for info output.

Returns:

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

SUNErrCode SUNLogger_GetInfoFile(SUNLogger logger, FILE **info_fp)

Gets the file pointer for info output.

Arguments:

• logger – a SUNLogger object.

• info_fp – on output, the file pointer used for info output.

Returns:

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

SUNErrCode 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. Passing an NULL or empty string disables output for this stream.

Returns:

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

SUNErrCode SUNLogger_SetDebugFile(SUNLogger logger, FILE *debug_fp)

Sets the file pointer for debug output.

The logger does not take ownership of debug_fp; the user is responsible for closing the file if needed. Passing NULL disables output for this stream.

Arguments:

• logger – a SUNLogger object.

• debug_fp – the FILE pointer to use for debug output.

Returns:

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

SUNErrCode SUNLogger_GetDebugFile(SUNLogger logger, FILE **debug_fp)

Gets the file pointer for debug output.

Arguments:

• logger – a SUNLogger object.

• debug_fp – on output, the file pointer used for debug output.

Returns:

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

SUNErrCode 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.

SUNErrCode 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.

SUNErrCode SUNLogger_SetQueueAndFlushMsgFns(SUNLogger logger, SUNLoggerQueueMsgFn queue_msg, SUNLoggerFlushMsgFn flush_msg, void *lptr)

Attaches user-defined functions to queue and flush log messages.

This function allows users to override the default message queueing and flushing behavior with custom implementations. Passing NULL for queue_msg resets the logger to use the default queue and flush functions.

Arguments:

• logger – a SUNLogger object

• queue_msg – the SUNLoggerQueueMsgFn function to use for queueing messages, or NULL to reset to the default implementation

• flush_msg – the SUNLoggerFlushMsgFn function to use for flushing messages, or NULL to disable flushing with SUNLogger_Flush()

• lptr – user-defined data pointer that will be passed to the queue_msg and flush_msg functions as the content parameter.

Returns:

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

SUNErrCode 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.

SUNErrCode 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.