CMake: prefix monitoring option with SUNDIALS_ (#867)

gardner48 · web-flow · commit dcfc06667b90 · 2026-03-09T22:08:19.000-07:00
`SUNDIALS_BUILD_WITH_MONITORING` -&gt; `SUNDIALS_ENABLE_MONITORING`
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -61,6 +61,7 @@ table below lists the old CMake option names and the new replacements.
 | `KOKKOS_KERNELS_WORKS`                  | `SUNDIALS_ENABLE_KOKKOS_KERNELS_CHECKS`        |
 | `BUILD_FORTRAN_MODULE_INTERFACE`        | `SUNDIALS_ENABLE_FORTRAN`                      |
 | `SUNDIALS_BUILD_WITH_PROFILING`         | `SUNDIALS_ENABLE_PROFILING`                    |
+| `SUNDIALS_BUILD_WITH_MONITORING`        | `SUNDIALS_ENABLE_MONITORING`                   |
 | `BUILD_BENCHMARKS`                      | `SUNDIALS_ENABLE_BENCHMARKS`                   |
 | `BENCHMARKS_INSTALL_PATH`               | `SUNDIALS_BENCHMARKS_INSTALL_PATH`             |
 | `SUNDIALS_BENCHMARK_OUTPUT_DIR`         | `SUNDIALS_BENCHMARKS_OUTPUT_DIR`               |
@@ -71,9 +72,10 @@ table below lists the old CMake option names and the new replacements.
 Following the updated CMake options, the macros listed below have been
 deprecated and replaced with versions that align with the new CMake options.
 
-| Old Macro                       | New Macro                   |
-|---------------------------------|-----------------------------|
-| `SUNDIALS_BUILD_WITH_PROFILING` | `SUNDIALS_ENABLE_PROFILING` |
+| Old Macro                        | New Macro                    |
+|----------------------------------|------------------------------|
+| `SUNDIALS_BUILD_WITH_PROFILING`  | `SUNDIALS_ENABLE_PROFILING`  |
+| `SUNDIALS_BUILD_WITH_MONITORING` | `SUNDIALS_ENABLE_MONITORING` |
 
 ## Changes to SUNDIALS in release 7.6.0
 
diff --git a/cmake/SundialsBuildOptionsPre.cmake b/cmake/SundialsBuildOptionsPre.cmake
@@ -71,7 +71,8 @@ set(SUNDIALS_COUNTER_TYPE
 # ---------------------------------------------------------------
 
 set(DOCSTR "Build with simulation monitoring capabilities enabled")
-sundials_option(SUNDIALS_BUILD_WITH_MONITORING BOOL "${DOCSTR}" OFF)
+sundials_option(SUNDIALS_ENABLE_MONITORING BOOL "${DOCSTR}" OFF
+                DEPRECATED_NAMES SUNDIALS_BUILD_WITH_MONITORING)
 
 # ---------------------------------------------------------------
 # Option to enable profiling
diff --git a/doc/cvode/guide/source/Usage/index.rst b/doc/cvode/guide/source/Usage/index.rst
@@ -981,7 +981,7 @@ Main solver optional input functions
 
       .. warning::
 
-         Modifying the solution in this function will result in  undefined behavior. This function is only intended to be used  for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
+         Modifying the solution in this function will result in  undefined behavior. This function is only intended to be used  for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_ENABLE_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
 
 .. c:function:: int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
@@ -1003,7 +1003,7 @@ Main solver optional input functions
 
       .. warning::
 
-         Modifying the solution in this function will result in undefined behavior. This function is only intended to be used for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
+         Modifying the solution in this function will result in undefined behavior. This function is only intended to be used for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_ENABLE_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
 
 .. c:function:: int CVodeSetMaxOrd(void* cvode_mem, int maxord)
 
diff --git a/doc/cvodes/guide/source/Usage/SIM.rst b/doc/cvodes/guide/source/Usage/SIM.rst
@@ -987,7 +987,7 @@ Main solver optional input functions
 
       .. warning::
 
-         Modifying the solution in this function will result in  undefined behavior. This function is only intended to be used  for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
+         Modifying the solution in this function will result in  undefined behavior. This function is only intended to be used  for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_ENABLE_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
 
 .. c:function:: int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
@@ -1009,7 +1009,7 @@ Main solver optional input functions
 
       .. warning::
 
-         Modifying the solution in this function will result in undefined behavior. This function is only intended to be used for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_BUILD_WITH_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
+         Modifying the solution in this function will result in undefined behavior. This function is only intended to be used for monitoring the integrator.  SUNDIALS must be built with the CMake option  ``SUNDIALS_ENABLE_MONITORING``, to utilize this function.  See :numref:`Installation` for more information.
 
 .. c:function:: int CVodeSetMaxOrd(void* cvode_mem, int maxord)
 
diff --git a/doc/shared/Changelog.rst b/doc/shared/Changelog.rst
@@ -2402,7 +2402,7 @@ contact the SUNDIALS team about any performance changes that they notice.
 Added new capabilities for monitoring the solve phase in the Newton and
 fixed-point :c:type:`SUNNonlinearSolver`, and the SUNDIALS iterative linear
 solvers. SUNDIALS must be built with the CMake option
-:cmakeop:`SUNDIALS_BUILD_WITH_MONITORING` to use these capabilities.
+``SUNDIALS_BUILD_WITH_MONITORING`` to use these capabilities.
 
 Added specialized fused CUDA kernels to CVODE which may offer better performance
 on smaller problems when using CVODE with the CUDA vector. See the optional
diff --git a/doc/shared/RecentChanges.rst b/doc/shared/RecentChanges.rst
@@ -100,6 +100,8 @@ table below lists the old CMake option names and the new replacements.
 +-------------------------------------------+---------------------------------------------------------+
 | ``SUNDIALS_BUILD_WITH_PROFILING``         | :cmakeop:`SUNDIALS_ENABLE_PROFILING`                    |
 +-------------------------------------------+---------------------------------------------------------+
+| ``SUNDIALS_BUILD_WITH_MONITORING``        | :cmakeop:`SUNDIALS_ENABLE_MONITORING`                   |
++-------------------------------------------+---------------------------------------------------------+
 | ``BUILD_BENCHMARKS``                      | :cmakeop:`SUNDIALS_ENABLE_BENCHMARKS`                   |
 +-------------------------------------------+---------------------------------------------------------+
 | ``BENCHMARKS_INSTALL_PATH``               | :cmakeop:`SUNDIALS_BENCHMARKS_INSTALL_PATH`             |
@@ -116,8 +118,10 @@ table below lists the old CMake option names and the new replacements.
 Following the updated CMake options, the macros listed below have been
 deprecated and replaced with versions that align with the new CMake options.
 
-+-----------------------------------+-------------------------------+
-| Old Macro                         | New Macro                     |
-+-----------------------------------+-------------------------------+
-| ``SUNDIALS_BUILD_WITH_PROFILING`` | ``SUNDIALS_ENABLE_PROFILING`` |
-+-----------------------------------+-------------------------------+
++------------------------------------+--------------------------------+
+| Old Macro                          | New Macro                      |
++------------------------------------+--------------------------------+
+| ``SUNDIALS_BUILD_WITH_PROFILING``  | ``SUNDIALS_ENABLE_PROFILING``  |
++------------------------------------+--------------------------------+
+| ``SUNDIALS_BUILD_WITH_MONITORING`` | ``SUNDIALS_ENABLE_MONITORING`` |
++------------------------------------+--------------------------------+
diff --git a/doc/shared/sundials/Install.rst b/doc/shared/sundials/Install.rst
@@ -800,7 +800,7 @@ For more information on logging in SUNDIALS, see :ref:`SUNDIALS.Logging`.
 Monitoring
 ^^^^^^^^^^
 
-.. cmakeoption:: SUNDIALS_BUILD_WITH_MONITORING
+.. cmakeoption:: SUNDIALS_ENABLE_MONITORING
 
    Build SUNDIALS with capabilities for fine-grained monitoring of solver
    progress and statistics. This is primarily useful for debugging.
@@ -812,6 +812,10 @@ Monitoring
       Building with monitoring may result in minor performance degradation even
       if monitoring is not utilized.
 
+   .. versionadded:: x.y.z
+
+      Replaces the deprecated option ``SUNDIALS_BUILD_WITH_MONITORING``
+
 .. _Installation.Options.Profiling:
 
 Profiling
diff --git a/examples/arkode/C_serial/CMakeLists.txt b/examples/arkode/C_serial/CMakeLists.txt
@@ -101,7 +101,7 @@ set(ARKODE_examples
     "ark_robertson.c\;\;exclude-single"
     "ark_twowaycouple_mri.c\;\;develop")
 
-if(SUNDIALS_BUILD_WITH_MONITORING)
+if(SUNDIALS_ENABLE_MONITORING)
   list(APPEND ARKODE_examples "ark_brusselator_fp.c\;1\;exclude-single")
 endif()
 
diff --git a/examples/cvode/serial/CMakeLists.txt b/examples/cvode/serial/CMakeLists.txt
@@ -41,7 +41,7 @@ set(CVODE_examples
     "cvRoberts_dns_uw\;\;develop"
     "cvRocket_dns\;\;develop")
 
-if(SUNDIALS_BUILD_WITH_MONITORING)
+if(SUNDIALS_ENABLE_MONITORING)
   list(APPEND CVODE_examples "cvKrylovDemo_ls\;0 1\;develop")
 endif()
 
diff --git a/examples/cvodes/serial/CMakeLists.txt b/examples/cvodes/serial/CMakeLists.txt
@@ -54,7 +54,7 @@ set(CVODES_examples
     "cvsRoberts_dns_constraints\;\;develop"
     "cvsRoberts_dns_uw\;\;develop")
 
-if(SUNDIALS_BUILD_WITH_MONITORING)
+if(SUNDIALS_ENABLE_MONITORING)
   list(APPEND CVODE_examples "cvsKrylovDemo_ls\;0 1\;develop")
 endif()
 
diff --git a/include/sundials/sundials_config.in b/include/sundials/sundials_config.in
@@ -99,7 +99,7 @@
 #cmakedefine SUNDIALS_BUILD_PACKAGE_FUSED_KERNELS
 
 /* BUILD SUNDIALS with monitoring functionalities */
-#cmakedefine SUNDIALS_BUILD_WITH_MONITORING
+#cmakedefine SUNDIALS_ENABLE_MONITORING
 
 /* BUILD SUNDIALS with profiling functionalities */
 #cmakedefine SUNDIALS_ENABLE_PROFILING
@@ -288,6 +288,12 @@
  * SUNDIALS deprecated macros
  * -----------------------------------------------------------------*/
 
+/* DEPRECATION NOTICE: SUNDIALS_BUILD_WITH_MONITORING will be removed in the
+ * next major release. Use SUNDIALS_ENABLE_MONITORING instead. */
+#ifdef SUNDIALS_ENABLE_MONITORING
+#define SUNDIALS_BUILD_WITH_MONITORING
+#endif
+
 /* DEPRECATION NOTICE: SUNDIALS_BUILD_WITH_PROFILING will be removed in the next
  * major release. Use SUNDIALS_ENABLE_PROFILING instead. */
 #ifdef SUNDIALS_ENABLE_PROFILING
diff --git a/src/cvode/cvode.c b/src/cvode/cvode.c
@@ -3596,7 +3596,7 @@ static void cvCompleteStep(CVodeMem cv_mem)
     cv_mem->cv_indx_acor = cv_mem->cv_qmax;
   }
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   /* If user access function was provided, call it now */
   if (cv_mem->cv_monitorfun != NULL &&
       !(cv_mem->cv_nst % cv_mem->cv_monitor_interval))
diff --git a/src/cvode/cvode_io.c b/src/cvode/cvode_io.c
@@ -105,7 +105,7 @@ int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn)
 
   cv_mem = (CVodeMem)cvode_mem;
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   cv_mem->cv_monitorfun = fn;
   return (CV_SUCCESS);
 #else
@@ -142,7 +142,7 @@ int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
   cv_mem = (CVodeMem)cvode_mem;
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   cv_mem->cv_monitor_interval = nst;
   return (CV_SUCCESS);
 #else
diff --git a/src/cvodes/cvodes.c b/src/cvodes/cvodes.c
@@ -7896,7 +7896,7 @@ static void cvCompleteStep(CVodeMem cv_mem)
     cv_mem->cv_indx_acor = cv_mem->cv_qmax;
   }
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   /* If user access function was provided, call it now */
   if (cv_mem->cv_monitorfun != NULL &&
       !(cv_mem->cv_nst % cv_mem->cv_monitor_interval))
diff --git a/src/cvodes/cvodes_io.c b/src/cvodes/cvodes_io.c
@@ -105,7 +105,7 @@ int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn)
 
   cv_mem = (CVodeMem)cvode_mem;
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   cv_mem->cv_monitorfun = fn;
   return (CV_SUCCESS);
 #else
@@ -142,7 +142,7 @@ int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
   cv_mem = (CVodeMem)cvode_mem;
 
-#ifdef SUNDIALS_BUILD_WITH_MONITORING
+#ifdef SUNDIALS_ENABLE_MONITORING
   cv_mem->cv_monitor_interval = nst;
   return (CV_SUCCESS);
 #else
