@@ -34,10 +34,6 @@ corresponding to errors, warnings, info output, and debug output where errors <
3434warnings < info output < debug output < extra debug output. By default only
3535warning and error messages are logged.
3636
37- .. note ::
38-
39- As of version 7.0.0, enabling MPI in SUNDIALS enables MPI-aware logging.
40-
4137When SUNDIALS is built with logging enabled, then the default logger (stored in
4238the :c:type: `SUNContext ` object) may be configured through environment variables
4339without any changes to user code. The available environment variables are:
@@ -50,34 +46,76 @@ without any changes to user code. The available environment variables are:
5046 SUNLOGGER_DEBUG_FILENAME
5147
5248
53- special filenames: ``stdout `` and ``stderr ``. These two filenames will
54- result in output going to the standard output file and standard error file.
55- The different variables may all be set to the same file, or to distinct files,
56- or some combination there of. To disable output for one of the streams, then
57- do not set the environment variable, or set it to an empty string.
49+ special filenames: ``stdout `` and ``stderr ``. These two filenames will result in
50+ output going to the standard output file and standard error file. For example,
51+ consider the CVODE Roberts example, where we can direct the informational output
52+ to the file ``sun.log `` as follows
5853
54+ .. code-block ::
55+
56+ SUNLOGGER_INFO_FILENAME=sun.log ./examples/cvode/serial/cvRoberts_dns
57+
58+
59+ distinct files, or some combination there of. To disable output for one of the
60+ streams, then do not set the environment variable, or set it to an empty string.
5961If :cmakeop: `SUNDIALS_LOGGING_LEVEL ` was set at build-time to a level lower than
6062the corresponding environment variable, then setting the environment variable
6163will do nothing. For example, if the logging level is set to ``2 `` (errors and
6264warnings), setting ``SUNLOGGER_INFO_FILENAME `` will do nothing.
6365
66+ Alternatively, the default logger can be accessed with
67+ :c:func: `SUNContext_GetLogger ` and configured using the
68+ :ref: `SUNDIALS.Logging.API ` or a user may create, configure, and attach a
69+ non-default logger using the :ref: `SUNDIALS.Logging.API `.
70+
6471.. warning ::
6572
66- A non-default logger should be created and attached to the context object prior
67- to any other SUNDIALS calls in order to capture all log events.
73+ A non-default logger should be created and attached to the context object
74+ prior to any other SUNDIALS calls in order to capture all log events.
75+
76+ The following examples demonstrate how to use the logging interface via the C
77+ API:
78+
79+ .. code-block ::
80+
81+ examples/arkode/CXX_serial/ark_analytic_sys.cpp
82+ examples/cvode/serial/cvAdvDiff_bnd.c
83+ examples/cvode/parallel/cvAdvDiff_diag_p.c
84+ examples/kinsol/CXX_parallel/kin_em_p.cpp
85+ examples/kinsol/CUDA_mpi/kin_em_mpicuda.cpp
86+
87+ SUNDIALS.Logging.Output :
88+
89+ Logging Output
90+ --------------
6891
6992Error or warning logs are a single line output with an error or warning message
93+ of the form
7094
7195.. code-block :: text
7296
7397 [level][rank][scope][label] message describing the error or warning
7498
99+
100+
101+ * ``level `` is the log level of the message and will be ``ERROR ``, ``WARNING ``,
102+ ``INFO ``, or ``DEBUG ``
103+
104+ * ``rank `` is the MPI rank the message was written from (``0 `` by default or if
105+ SUNDIALS was built without MPI enabled)
106+
107+ * ``scope `` is the message scope i.e., the name of the function from which the
108+ message was written
109+
110+ * ``label `` provides additional context or information about the logging
111+ output e.g., ``begin-step ``, ``end-linear-solve ``, etc.
112+
75113Informational or debugging logs are either a single line output with a
76114comma-separated list of key-value pairs of the form
77115
78116.. code-block :: text
79117
80- [level][rank][scope][label] key1 = value , key2 = value
118+ [level][rank][scope][label] key1 = value1 , key2 = value2
81119
82120
83121or array e.g.,
@@ -89,26 +127,44 @@ or array e.g.,
89127 y[1]
90128 ...
91129
92-
93- meaning:
130+ note ::
94131
95- * ``level `` is the log level of the message and will be ``ERROR ``, ``WARNING ``,
96- ``INFO ``, or ``DEBUG ``
132+ When extra debugging output is enabled, the output will include vector values
133+ (so long as the :c:type: `N_Vector ` used supports printing). Depending on the
134+ problem size, this may result in very large logging files.
97135
98- * ``rank `` is the MPI rank the message was written from (``0 `` by default or if
99- SUNDIALS was built without MPI enabled)
136+ .. _SUNDIALS.Logging.Tools :
100137
101- * `` scope `` is the message scope i.e., the name of the function from which the
102- message was written
138+ Logging Tools
139+ -------------
103140
104- * ``label `` provides additional context or information about the logging
105- output e.g., ``begin-step ``, ``end-linear-solve ``, etc.
141+ .. versionadded :: 7.2.0
106142
107- .. note ::
143+ To assist with extracting data from logging output files, the ``tools ``
144+ directory contains the ``suntools `` Python module which provides utilities for
145+ parsing log files in the ``logs `` sub-module.
108146
109- When extra debugging output is enabled, the output will include vector values
110- (so long as the :c:type: `N_Vector ` used supports printing). Depending on the
111- problem size, this may result in very large logging files.
147+ .. autofunction :: logs.log_file_to_list
148+
149+ .. autofunction :: logs.print_log
150+
151+ .. autofunction :: logs.get_history
152+
153+ The ``tools `` directory also contains example scripts demonstrating how to use
154+ the log parsing functions to extract and plot data.
155+
156+ * ``log_example_print.py `` -- parses a log file and prints the log file list.
157+
158+ * ``log_example.py `` -- plots the step size, order, or error estimate history
159+ from an ARKODE, CVODE(S), or IDA(S) log file.
160+
161+ * ``log_example_mri.py `` -- plots the step size history from an ARKODE MRIStep
162+ log file.
163+
164+ For more details on using an example script, run the script with the ``--help ``
165+ flag.
166+
167+ .. _SUNDIALS.Logging.API :
112168
113169Logger API
114170----------
@@ -259,15 +315,6 @@ The :c:type:`SUNLogger` class provides the following methods.
259315 **Returns:**
260316 * Returns zero if successful, or non-zero if an error occurred.
261317
262- .. warning::
263-
264- When compiling for ANSI C / C89 / C90 (and without compiler extensions),
265- it is dangerous to pass any user input to this function because it falls
266- back to using ``sprintf`` with a fixed buffer size.
267-
268- It is **highly recommended** to compile with C99 or newer if your compiler
269- does not support ``snprintf`` through extensions.
270-
271318
272319.. c:function:: int SUNLogger_Flush(SUNLogger logger, SUNLogLevel lvl)
273320
@@ -304,42 +351,3 @@ The :c:type:`SUNLogger` class provides the following methods.
304351
305352 **Returns:**
306353 * Returns zero if successful, or non-zero if an error occur.
307-
308-
309- .. _SUNDIALS.Logging.Example:
310-
311- Example Usage
312- -------------
313-
314- As noted above, enabling logging must be done when configuring SUNDIALS by
315- setting the CMake option :cmakeop:`SUNDIALS_LOGGING_LEVEL` to the desired
316- logging level. When running a program with SUNDIALS logging enabled, a default
317- logger is created and attached to the :c:type:`SUNContext` instance at creation.
318- Environment variables or run-time functions can be used to determine where the
319- logging output is written. For example, consider the CVODE Roberts example, where
320- we can direct the informational output to the file ``sun.log`` as follows
321-
322- .. code-block::
323-
324- SUNLOGGER_INFO_FILENAME=sun.log ./examples/cvode/serial/cvRoberts_dns
325-
326- Alternatively, the following examples demonstrate how to use the logging
327- interface via the C API:
328-
329- .. code-block::
330-
331- examples/arkode/CXX_serial/ark_analytic_sys.cpp
332- examples/cvode/serial/cvAdvDiff_bnd.c
333- examples/cvode/parallel/cvAdvDiff_diag_p.c
334- examples/kinsol/CXX_parallel/kin_em_p.cpp
335- examples/kinsol/CUDA_mpi/kin_em_mpicuda.cpp
336-
337- To assist with extracting informational logging data from output files the
338- ``tools`` directory contains a Python module, ``suntools``, that provides
339- utilities for parsing log files. Some example scripts using the ``suntools``
340- module are included in the ``tools`` directory. For example, we can plot the
341- step size history from the CVODE Roberts problem with
342-
343- .. code-block::
344-
345- ./log_example.py sun.log
0 commit comments