deprecate cvode monitor function(s)

CHANGELOG.md

@@ -58,6 +58,9 @@ the next major release. Use `SUN_CSC_MAT` and `SUN_CSR_MAT` instead.
 
 The `N_Vector_S` typedef to `N_Vector*` is deprecated and will be removed in the next major release.
 
+The `CVodeSetMonitorFn` and `CVodeSetMonitorFrequency` functions have been deprecated and will be
+removed in the next major release.
+
 ## Changes to SUNDIALS in release 7.5.0
 
 ### Major Features

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

@@ -980,6 +980,8 @@ Main solver optional input functions
 
          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.
 
+   .. deprecated:: x.y.z.
+
 .. c:function:: int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
    The function ``CVodeSetMonitorFrequency`` specifies the  interval, measured in successfully completed CVODE time-steps,  at which the monitor function should be called.
@@ -1002,6 +1004,8 @@ Main solver optional input functions
 
          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.
 
+   .. deprecated:: x.y.z.
+
 .. c:function:: int CVodeSetMaxOrd(void* cvode_mem, int maxord)
 
    The function ``CVodeSetMaxOrd`` specifies the maximum order of the  linear multistep method.

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

@@ -985,6 +985,8 @@ Main solver optional input functions
 
          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.
 
+   .. deprecated:: x.y.z.
+
 .. c:function:: int CVodeSetMonitorFrequency(void* cvode_mem, long int nst)
 
    The function ``CVodeSetMonitorFrequency`` specifies the  interval, measured in successfully completed CVODES time-steps,  at which the monitor function should be called.
@@ -1007,6 +1009,8 @@ Main solver optional input functions
 
          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.
 
+   .. deprecated:: x.y.z.
+
 .. c:function:: int CVodeSetMaxOrd(void* cvode_mem, int maxord)
 
    The function ``CVodeSetMaxOrd`` specifies the maximum order of the  linear multistep method.

doc/shared/RecentChanges.rst

@@ -56,3 +56,6 @@ The ``CSC_MAT`` and ``CSR_MAT`` macros defined in ``sunmatrix_sparse.h`` will be
 the next major release. Use ``SUN_CSC_MAT`` and ``SUN_CSR_MAT`` instead.
 
 The ``N_Vector_S`` typedef to ``N_Vector*`` is deprecated and will be removed in the next major release.
+
+The ``CVodeSetMonitorFn`` and ``CVodeSetMonitorFrequency`` functions have been deprecated and will be
+removed in the next major release.

examples/cvode/serial/cvKrylovDemo_ls.c

@@ -180,8 +180,6 @@ static int Precond(sunrealtype tn, N_Vector u, N_Vector fu, sunbooleantype jok,
 static int PSolve(sunrealtype tn, N_Vector u, N_Vector fu, N_Vector r, N_Vector z,
                   sunrealtype gamma, sunrealtype delta, int lr, void* user_data);
 
-static int myMonitorFunction(void* cvode_mem, void* user_data);
-
 /*
  *-------------------------------
  * Main Program
@@ -199,7 +197,7 @@ int main(int argc, char* argv[])
   int linsolver, iout, retval;
   int nrmfactor;      /* LS norm conversion factor flag */
   sunrealtype nrmfac; /* LS norm conversion factor      */
-  int monitor;        /* LS resiudal monitoring flag    */
+  int monitor;        /* LS residual monitoring flag    */
   SUNContext sunctx;
   SUNLogger logger;
   const char* info_fname = "cvKrylovDemo_ls-info.txt";
@@ -263,16 +261,6 @@ int main(int argc, char* argv[])
   retval = CVodeSStolerances(cvode_mem, reltol, abstol);
   if (check_retval(&retval, "CVodeSStolerances", 1)) { return (1); }
 
-  /* Set a function that CVode will call every 50 successful time steps.
-   * This will be used to monitor the solution and integrator statistics. */
-  if (monitor)
-  {
-    retval = CVodeSetMonitorFn(cvode_mem, myMonitorFunction);
-    if (check_retval(&retval, "CVodeSetMonitorFn", 1)) { return (1); }
-    retval = CVodeSetMonitorFrequency(cvode_mem, 50);
-    if (check_retval(&retval, "CVodeSetMonitorFrequency", 1)) { return (1); }
-  }
-
   /* Create the SUNNonlinearSolver */
   NLS = SUNNonlinSol_Newton(u, sunctx);
   if (check_retval(&retval, "SUNNonlinSol_Newton", 0)) { return (1); }
@@ -891,17 +879,3 @@ static int PSolve(sunrealtype tn, N_Vector u, N_Vector fu, N_Vector r, N_Vector
 
   return (0);
 }
-
-/* Function that is called at some step interval by CVODE */
-
-static int myMonitorFunction(void* cvode_mem, void* user_data)
-{
-  UserData data = (UserData)user_data;
-  sunrealtype t = 0;
-
-  CVodeGetCurrentTime(cvode_mem, &t);
-  PrintOutput(cvode_mem, data->u, t);
-  PrintStats(cvode_mem, data->linsolver, 0);
-
-  return (0);
-}

include/cvode/cvode.h

@@ -97,6 +97,7 @@ typedef int (*CVRootFn)(sunrealtype t, N_Vector y, sunrealtype* gout_1d,
 
 typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void* user_data);
 
+/* DEPRECATION NOTICE: this will be removed in v8.0.0 */
 typedef int (*CVMonitorFn)(void* cvode_mem, void* user_data);
 
 /* -------------------
@@ -138,8 +139,10 @@ SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void* cvode_mem, long int mxsteps);
 SUNDIALS_EXPORT int CVodeSetMaxOrd(void* cvode_mem, int maxord);
 SUNDIALS_EXPORT int CVodeSetMaxStep(void* cvode_mem, sunrealtype hmax);
 SUNDIALS_EXPORT int CVodeSetMinStep(void* cvode_mem, sunrealtype hmin);
-SUNDIALS_EXPORT int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn);
-SUNDIALS_EXPORT int CVodeSetMonitorFrequency(void* cvode_mem, long int nst);
+SUNDIALS_DEPRECATED_EXPORT
+int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn);
+SUNDIALS_DEPRECATED_EXPORT
+int CVodeSetMonitorFrequency(void* cvode_mem, long int nst);
 SUNDIALS_EXPORT int CVodeSetNlsRhsFn(void* cvode_mem, CVRhsFn f);
 SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void* cvode_mem, sunrealtype nlscoef);
 SUNDIALS_EXPORT int CVodeSetNonlinearSolver(void* cvode_mem,

include/cvodes/cvodes.h

@@ -141,6 +141,7 @@ typedef int (*CVRootFn)(sunrealtype t, N_Vector y, sunrealtype* gout_1d,
 
 typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void* user_data);
 
+/* DEPRECATION NOTICE: this will be removed in v8.0.0 */
 typedef int (*CVMonitorFn)(void* cvode_mem, void* user_data);
 
 typedef int (*CVQuadRhsFn)(sunrealtype t, N_Vector y, N_Vector yQdot,
@@ -209,8 +210,10 @@ SUNDIALS_EXPORT int CVodeSetMaxNumSteps(void* cvode_mem, long int mxsteps);
 SUNDIALS_EXPORT int CVodeSetMaxOrd(void* cvode_mem, int maxord);
 SUNDIALS_EXPORT int CVodeSetMaxStep(void* cvode_mem, sunrealtype hmax);
 SUNDIALS_EXPORT int CVodeSetMinStep(void* cvode_mem, sunrealtype hmin);
-SUNDIALS_EXPORT int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn);
-SUNDIALS_EXPORT int CVodeSetMonitorFrequency(void* cvode_mem, long int nst);
+SUNDIALS_DEPRECATED_EXPORT
+int CVodeSetMonitorFn(void* cvode_mem, CVMonitorFn fn);
+SUNDIALS_DEPRECATED_EXPORT
+int CVodeSetMonitorFrequency(void* cvode_mem, long int nst);
 SUNDIALS_EXPORT int CVodeSetNlsRhsFn(void* cvode_mem, CVRhsFn f);
 SUNDIALS_EXPORT int CVodeSetNonlinConvCoef(void* cvode_mem, sunrealtype nlscoef);
 SUNDIALS_EXPORT int CVodeSetNonlinearSolver(void* cvode_mem,