Add macro for consistent sunrealtype formatting

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

@@ -57,6 +57,23 @@ jobs:
         --label-regex logging \
         --verbose
 
+    - name: Archive build files from failed build
+      uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: build_files
+        path: |
+          ${{ github.workspace }}/build
+          !${{ github.workspace }}/build/Testing/output
+
+    - name: Archive output files from failed build
+      uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: output_files
+        path: |
+          ${{ github.workspace }}/build/Testing/
+
   build_cycle_profiling:
     runs-on: ubuntu-latest
 
@@ -82,3 +99,20 @@ jobs:
     - name: Build
       # Build your program with the given configuration
       run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
+
+    - name: Archive build files from failed build
+      uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: build_files
+        path: |
+          ${{ github.workspace }}/build
+          !${{ github.workspace }}/build/Testing/output
+
+    - name: Archive output files from failed build
+      uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: output_files
+        path: |
+          ${{ github.workspace }}/build/Testing/

doc/superbuild/source/developers/source_code/Rules.rst

@@ -196,4 +196,7 @@ not adhere to all of these rules.
    ``sunindextype`` for it. Instead use the appropriate integer type (e.g., ``uint64_t``) directly.
    Do not use ``sunindextype`` for counters either.
 
+#. Use the print functions, format macros, and output guidelines detailed in
+   :ref:`Style.Output`.
+
 #. Follow the logging style detailed in :ref:`Style.Logging`.

doc/superbuild/source/developers/source_code/Style.rst

@@ -107,6 +107,83 @@ doing this type of line break is useful for readability too.
 .. See the clang-tidy documentation for more details.
 
 
+.. _Style.Output:
+
+Output
+------
+
+For consistent formatting of :c:type:`sunrealtype`, the following macros are
+available.
+
+.. c:macro:: SUN_FORMAT_E
+
+   A format specifier for scientific notation. This should be used when
+   displaying arrays, matrices, and tables where fixed width alignment aids with
+   readability.
+
+   **Example usage:**
+
+   .. code-block:: C
+
+      for (i = 0; i < N; i++) {
+         fprintf(outfile, SUN_FORMAT_E "\n", xd[i]);
+      }
+
+.. c:macro:: SUN_FORMAT_G
+
+   A format specifier for scientific or standard notation, whichever is more
+   compact. It is more reader-friendly than :c:macro:`SUN_FORMAT_E` and should
+   be used in all cases not covered by that macro.
+
+   **Example usage:**
+
+   .. code-block:: C
+
+      SSUNLogInfo(sunctx->logger, "label", "x = " SUN_FORMAT_G, x);
+
+.. c:macro:: SUN_FORMAT_SG
+
+   Like :c:macro:`SUN_FORMAT_G` but with a leading plus or minus sign.
+
+
+To aid in printing statistics in functions like :c:func:`CVodePrintAllStats`,
+the following utility functions are available.
+
+.. c:function:: void sunfprintf_real(FILE* fp, SUNOutputFormat fmt, sunbooleantype start, const char* name, sunrealtype value)
+
+   Writes a :c:type:`sunrealtype` value to a file pointer using the specified
+   format.
+
+   :param fp: Pointer to output file.
+   :param fmt: The output format.
+   :param start: :c:macro:`SUNTRUE` if the value is the first in a series of
+                 statistics, and :c:macro:`SUNFALSE` otherwise.
+   :param name: The name of the statistic.
+   :param value: The value of the statistic.
+
+.. c:function:: void sunfprintf_long(FILE* fp, SUNOutputFormat fmt, sunbooleantype start, const char* name, long value)
+
+   Writes a long value to a file pointer using the specified format.
+
+   :param fp: Pointer to output file.
+   :param fmt: The output format.
+   :param start: :c:macro:`SUNTRUE` if the value is the first in a series of
+                 statistics, and :c:macro:`SUNFALSE` otherwise.
+   :param name: The name of the statistic.
+   :param value: The value of the statistic.
+
+.. c:function:: void sunfprintf_long_array(FILE* fp, SUNOutputFormat fmt, sunbooleantype start, const char* name, long* value, size_t count)
+
+   Writes an array of long values to a file pointer using the specified format.
+
+   :param fp: Pointer to output file.
+   :param fmt: The output format.
+   :param start: :c:macro:`SUNTRUE` if the value is the first in a series of
+                 statistics, and :c:macro:`SUNFALSE` otherwise.
+   :param name: The name of the statistic.
+   :param value: Pointer to the array.
+   :param count: The number of elements in the array.
+
 .. _Style.Logging:
 
 Logging
@@ -128,10 +205,12 @@ equals sign with a space on either side e.g.,
 .. code-block:: C
 
    /* log an informational message */
-   SUNLogInfo(sunctx->logger, "begin-step", "t = %g, h = %g", t, h);
+   SUNLogInfo(sunctx->logger, "begin-step", "t = " SUN_FORMAT_G ", h = " SUN_FORMAT_G, t, h);
 
    /* log a debugging message */
-   SUNLogDebug(sunctx->logger, "error-estimates", "eqm1 = %g, eq = %g, eqp1 = %g", eqm1, eq, eqp1);
+   SUNLogDebug(sunctx->logger, "error-estimates",
+               "eqm1 = " SUN_FORMAT_G ", eq = " SUN_FORMAT_G ", eqp1 = " SUN_FORMAT_G,
+               eqm1, eq, eqp1);
 
 or the name of a vector/array followed by ``(:) =`` with each vector/array entry
 written to a separate line e.g., a vector may be logged with

examples/arkode/CXX_manyvector/ark_sod_lsrk.out

@@ -41,8 +41,8 @@ Accuracy limited steps       = 397
 Error test fails             = 15
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 1.122284259749542e-14
-Last step size               = 0.0002334416078592081
-Current step size            = 0.0002334416078592081
+Initial step size            = 1.12228425974954e-14
+Last step size               = 0.000233441607859208
+Current step size            = 0.000233441607859208
 RHS fn evals                 = 3957
 Number of stages used        = 10

examples/arkode/CXX_parallel/ark_heat2D_lsrk_p_--np_2_2.out

@@ -65,9 +65,10 @@ Accuracy limited steps       = 617
 Error test fails             = 0
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 2.877680248425019e-06
-Last step size               = 0.0003228665778641779
-Current step size            = 0.0003228665778641779
+Initial step size            = 2.87768024842502e-06
+Last step size               = 0.000322866577864178
+Current step size            = 0.000322866577864178
+RHS fn evals                 = 17225
 RHS fn evals                 = 17225
 Number of dom_eig updates    = 25
 Max. num. of stages used     = 46

examples/arkode/CXX_serial/ark_heat2D_lsrk.out

@@ -59,9 +59,10 @@ Accuracy limited steps       = 617
 Error test fails             = 0
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 2.877680248425025e-06
-Last step size               = 0.0003199001977636226
-Current step size            = 0.0003199001977636226
+Initial step size            = 2.87768024842502e-06
+Last step size               = 0.000319900197763623
+Current step size            = 0.000319900197763623
+RHS fn evals                 = 17225
 RHS fn evals                 = 17225
 Number of dom_eig updates    = 25
 Max. num. of stages used     = 46

examples/arkode/C_serial/ark_advection_diffusion_reaction_splitting.out

@@ -37,11 +37,11 @@ Error test fails             = 0
 NLS step fails               = 0
 Inequality constraint fails  = 0
 Initial step size            = 0.06
-Last step size               = 0.03999999999999956
+Last step size               = 0.0399999999999996
 Current step size            = 0.06
-Partition 0 evolves          = 17
 Partition 1 evolves          = 17
 Partition 2 evolves          = 17
+Partition 3 evolves          = 17
 
 Advection Stepper Statistics:
 Current time                 = 1
@@ -52,9 +52,9 @@ Accuracy limited steps       = 64
 Error test fails             = 9
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 2.059355438929501e-06
-Last step size               = 0.004032057223863014
-Current step size            = 0.004032057223863014
+Initial step size            = 2.0593554389295e-06
+Last step size               = 0.00403205722386301
+Current step size            = 0.00403205722386301
 RHS fn evals                 = 185
 
 Diffusion Stepper Statistics:
@@ -66,14 +66,14 @@ Accuracy limited steps       = 302
 Error test fails             = 55
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 2.059355438929501e-06
-Last step size               = 0.006555275857754277
-Current step size            = 0.006555275857754277
+Initial step size            = 2.0593554389295e-06
+Last step size               = 0.00655527585775428
+Current step size            = 0.00655527585775428
 Explicit RHS fn evals        = 0
 Implicit RHS fn evals        = 1831
 NLS iters                    = 906
 NLS fails                    = 0
-NLS iters per step           = 3.668016194331984
+NLS iters per step           = 3.66801619433198
 LS setups                    = 213
 Jac fn evals                 = 72
 LS RHS fn evals              = 0
@@ -84,7 +84,7 @@ LS fails                     = 0
 Jac-times setups             = 0
 Jac-times evals              = 0
 LS iters per NLS iter        = 0
-Jac evals per NLS iter       = 0.07947019867549669
+Jac evals per NLS iter       = 0.0794701986754967
 Prec evals per NLS iter      = 0
 
 Reaction Stepper Statistics:
@@ -97,6 +97,6 @@ Error test fails             = 7
 NLS step fails               = 0
 Inequality constraint fails  = 0
 Initial step size            = 0.00180442856879795
-Last step size               = 0.03999999999999956
-Current step size            = 0.03999999999999956
+Last step size               = 0.0399999999999996
+Current step size            = 0.0399999999999996
 RHS fn evals                 = 166

examples/arkode/C_serial/ark_analytic_lsrk.out

@@ -19,22 +19,23 @@ Analytical ODE test problem:
    ---------------------
 
 Final Statistics:
-Current time                 = 10.00468816776983
+Current time                 = 10.0046881677698
 Steps                        = 1454
 Step attempts                = 1457
 Stability limited steps      = 30
 Accuracy limited steps       = 1457
 Error test fails             = 3
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 1.930101110942615e-10
+Initial step size            = 1.93010111094261e-10
 Last step size               = 0.019104
-Current step size            = 0.02996850857415225
+Current step size            = 0.0299685085741523
+RHS fn evals                 = 160396
 RHS fn evals                 = 160396
 Number of dom_eig updates    = 1
 Max. num. of stages used     = 196
 Max. num. of stages allowed  = 200
 Max. spectral radius         = 1010000
 Min. spectral radius         = 1010000
 
-ACCURACY at the final time   = 9.76996e-14
+ACCURACY at the final time   = 9.76996e-14

examples/arkode/C_serial/ark_analytic_lsrk_varjac.out

@@ -1,3 +1,4 @@
+
 Analytical ODE test problem with a variable Jacobian:
 The stiffness of the problem is directly proportional to
 "lambda - alpha*cos((10 - t)/10*pi)"
@@ -30,14 +31,15 @@ Accuracy limited steps       = 1653
 Error test fails             = 2
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 1.930101110942615e-10
-Last step size               = 0.02203090645841201
-Current step size            = 0.02203090645841201
+Initial step size            = 1.93010111094261e-10
+Last step size               = 0.022030906458412
+Current step size            = 0.022030906458412
+RHS fn evals                 = 150640
 RHS fn evals                 = 150640
 Number of dom_eig updates    = 68
 Max. num. of stages used     = 187
 Max. num. of stages allowed  = 200
-Max. spectral radius         = 1010099.739553962
+Max. spectral radius         = 1010099.73955396
 Min. spectral radius         = 1009899
 
-ACCURACY at the final time   = 1.54099e-13
+ACCURACY at the final time   = 1.54099e-13

examples/arkode/C_serial/ark_analytic_nonlin.out

@@ -18,15 +18,15 @@ Analytical ODE test problem:
    ---------------------
 
 Final Statistics:
-Current time                 = 10.12157090914652
+Current time                 = 10.1215709091465
 Steps                        = 82
 Step attempts                = 83
 Stability limited steps      = 0
 Accuracy limited steps       = 83
 Error test fails             = 1
 NLS step fails               = 0
 Inequality constraint fails  = 0
-Initial step size            = 6.103515625000001e-12
-Last step size               = 0.4463519264234082
-Current step size            = 0.4463519264234082
+Initial step size            = 6.103515625e-12
+Last step size               = 0.446351926423408
+Current step size            = 0.446351926423408
 RHS fn evals                 = 417

examples/arkode/C_serial/ark_analytic_partitioned_forcing.out

@@ -6,7 +6,7 @@ Analytical ODE test problem:
 Error: 0.00185186
 
 Splitting Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 100
 Step attempts                = 100
 Stability limited steps      = 0
@@ -17,11 +17,11 @@ Inequality constraint fails  = 0
 Initial step size            = 0.01
 Last step size               = 0.01
 Current step size            = 0.01
-Partition 0 evolves          = 100
 Partition 1 evolves          = 100
+Partition 2 evolves          = 100
 
 Linear Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 500
 Step attempts                = 500
 Stability limited steps      = 0
@@ -35,7 +35,7 @@ Current step size            = 0.002
 RHS fn evals                 = 2500
 
 Nonlinear Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 1000
 Step attempts                = 1000
 Stability limited steps      = 0

examples/arkode/C_serial/ark_analytic_partitioned_splitting.out

@@ -6,7 +6,7 @@ Analytical ODE test problem:
 Error: 0.001796
 
 Splitting Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 100
 Step attempts                = 100
 Stability limited steps      = 0
@@ -17,11 +17,11 @@ Inequality constraint fails  = 0
 Initial step size            = 0.01
 Last step size               = 0.01
 Current step size            = 0.01
-Partition 0 evolves          = 100
 Partition 1 evolves          = 100
+Partition 2 evolves          = 100
 
 Linear Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 500
 Step attempts                = 500
 Stability limited steps      = 0
@@ -35,7 +35,7 @@ Current step size            = 0.002
 RHS fn evals                 = 2500
 
 Nonlinear Stepper Statistics:
-Current time                 = 1.000000000000001
+Current time                 = 1
 Steps                        = 1000
 Step attempts                = 1000
 Stability limited steps      = 0