Feature: Logging Updates (#501)

Follow on to utilities added in #499 
* Make info logging output in the integrators more consistent 
* Update parser for MRI and operator splitting methods
* Add function to extract lists of data for plotting
* Add example scripts using log parser

---------

Co-authored-by: Steven Roberts <roberts115@llnl.gov>
Co-authored-by: Daniel R. Reynolds <reynolds@smu.edu>
Co-authored-by: Cody Balos <balos1@llnl.gov>

.cmake-format.py

@@ -59,6 +59,7 @@
                                        'EXTRA_ARGS': '+',
                                        'FLOAT_PRECISION': 1,
                                        'INTEGER_PRECISION': 1,
+                                       'LABELS': '+',
                                        'MPI_NPROCS': 1,
                                        'TEST_ARGS': '+'},
                            'pargs': {'flags': ['NODIFF'], 'nargs': '2+'}},

.github/workflows/ubuntu-clang-latest.yml

@@ -43,12 +43,25 @@ jobs:
         -D CMAKE_CXX_COMPILER=$(which clang++) \
         -D SUNDIALS_LOGGING_LEVEL=${{matrix.logging_level}} \
         -D ENABLE_ALL_WARNINGS=ON \
-        -D ENABLE_WARNINGS_AS_ERRORS=ON
+        -D ENABLE_WARNINGS_AS_ERRORS=ON \
+        -D SUNDIALS_TEST_DEVTESTS=ON \
+        -D SUNDIALS_TEST_UNITTESTS=ON \
+        -D SUNDIALS_TEST_ENABLE_GTEST=OFF \
+        -D SUNDIALS_TEST_FLOAT_PRECISION=4 \
+        -D SUNDIALS_TEST_INTEGER_PRECISION=10
 
     - name: Build
       # Build your program with the given configuration
       run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
 
+    - name: Test
+      # Run logging tests
+      run: |
+        ctest \
+        --test-dir ${{github.workspace}}/build \
+        --label-regex logging \
+        --verbose
+
   build_cycle_profiling:
     runs-on: ubuntu-latest
 

.gitignore

@@ -77,3 +77,6 @@ uberenv_libs
 
 # swig
 /swig/swig
+
+# tools
+/tools/suntools/__pycache__

CHANGELOG.md

@@ -45,6 +45,12 @@ backends with Trilinos.  As such, Trilinos 14 or newer is required and the
 
 Example programs using *hypre* have been updated to support v2.20 and newer.
 
+The information level logging output in ARKODE, CVODE(S), and IDA(S) has been
+updated to be more uniform across the packages and a new `tools` directory
+has been added with a Python module, `suntools`, containing utilities for
+parsing logging output. The Python utilities for parsing CSV output have been
+relocated from the `scripts` directory to the Python module.
+
 The build system has been updated to utilize the CMake LAPACK imported target
 which should ease building SUNDIALS with LAPACK libraries that require setting
 specific linker flags e.g., MKL.

cmake/macros/SundialsAddTest.cmake

@@ -21,7 +21,8 @@
 #                   [ANSWER_DIR path]
 #                   [ANSWER_FIEL file]
 #                   [EXAMPLE_TYPE type]
-#                   [TEST_ARGS arg1 arg2 ...])
+#                   [TEST_ARGS arg1 arg2 ...]
+#                   [LABELS label1 label2 ...])
 # ~~~
 #
 # CMake macro to add a SUNDIALS regression test. Keyword input arguments can be
@@ -46,6 +47,11 @@
 #
 # The option EXAMPLE_TYPE set the example type i.e., release or develop examples
 #
+# The option TEST_ARGS are command line arguments to pass to the executable
+#
+# The options LABELS are labels added to the test properties to easily run (or
+# exclude) groups of test with ctest -L <label> (or ctest -LE <label>)
+#
 # When SUNDIALS_TEST_DEVTESTS is OFF (default) the executable is run and success
 # or failure is determined by the executable return value (zero or non-zero
 # respectively).
@@ -83,7 +89,7 @@ macro(SUNDIALS_ADD_TEST NAME EXECUTABLE)
   set(options "NODIFF")
   set(oneValueArgs "MPI_NPROCS" "FLOAT_PRECISION" "INTEGER_PRECISION"
                    "ANSWER_DIR" "ANSWER_FILE" "EXAMPLE_TYPE")
-  set(multiValueArgs "TEST_ARGS" "EXTRA_ARGS")
+  set(multiValueArgs "LABELS" "TEST_ARGS" "EXTRA_ARGS")
 
   # parse inputs and create variables SUNDIALS_ADD_TEST_<keyword>
   cmake_parse_arguments(SUNDIALS_ADD_TEST "${options}" "${oneValueArgs}"
@@ -282,6 +288,14 @@ macro(SUNDIALS_ADD_TEST NAME EXECUTABLE)
 
     endif()
 
+    if(SUNDIALS_TEST_DEVTESTS OR NOT SUNDIALS_ADD_TEST_EXAMPLE_TYPE)
+      # set any labels (must quote SUNDIALS_ADD_TEST_LABELS)
+      if(SUNDIALS_ADD_TEST_LABELS)
+        set_tests_properties(${NAME} PROPERTIES LABELS
+                                                "${SUNDIALS_ADD_TEST_LABELS}")
+      endif()
+    endif()
+
   endif()
 
 endmacro()

doc/arkode/guide/source/Usage/ARKStep/User_callable.rst

@@ -3060,9 +3060,9 @@ Main solver optional output functions
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 5.2.0
 

doc/arkode/guide/source/Usage/ERKStep/User_callable.rst

@@ -1644,9 +1644,9 @@ Main solver optional output functions
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 5.2.0
 

doc/arkode/guide/source/Usage/MRIStep/User_callable.rst

@@ -1724,9 +1724,9 @@ Main solver optional output functions
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 5.2.0
 

doc/arkode/guide/source/Usage/SPRKStep/User_callable.rst

@@ -738,9 +738,9 @@ Main solver optional output functions
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. deprecated:: 6.1.0
 

doc/arkode/guide/source/Usage/User_callable.rst

@@ -3542,9 +3542,9 @@ Retrieve the accumulated temporal error estimate       :c:func:`ARKodeGetAccumul
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 6.1.0
 

doc/cvode/guide/source/Usage/index.rst

@@ -2736,9 +2736,9 @@ described next.
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 6.2.0
 

doc/cvodes/guide/source/Usage/SIM.rst

@@ -2736,9 +2736,9 @@ described next.
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 6.2.0
 

doc/ida/guide/source/Usage/index.rst

@@ -2602,9 +2602,9 @@ described next.
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 6.2.0
 

doc/idas/guide/source/Usage/SIM.rst

@@ -2631,9 +2631,9 @@ described next.
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 5.2.0
 

doc/kinsol/guide/source/Usage/index.rst

@@ -1474,9 +1474,9 @@ functions are described next.
 
    .. note::
 
-      The file ``scripts/sundials_csv.py`` provides python utility functions to
-      read and output the data from a SUNDIALS CSV output file using the key
-      and value pair format.
+      The Python module ``tools/suntools`` provides utilities to read and output
+      the data from a SUNDIALS CSV output file using the key and value pair
+      format.
 
    .. versionadded:: 6.2.0
 

doc/shared/RecentChanges.rst

@@ -53,6 +53,12 @@ backends with Trilinos. As such, Trilinos 14 or newer is required and the
 
 Example programs using *hypre* have been updated to support v2.20 and newer.
 
+The information level logging output in ARKODE, CVODE(S), and IDA(S) has been
+updated to be more uniform across the packages and a new ``tools`` directory
+has been added with a Python module, ``suntools``, containing utilities for
+parsing logging output. The Python utilities for parsing CSV output have been
+relocated from the ``scripts`` directory to the Python module.
+
 The build system has been updated to utilize the CMake LAPACK imported target
 which should ease building SUNDIALS with LAPACK libraries that require setting
 specific linker flags e.g., MKL.