Maintenance/arkode UI

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Changes to SUNDIALS in release X.Y.Z
 
+Created shared user interface for ARKODE user-callable routines, to allow more
+uniform control over time-stepping algorithms, improved extensibility, and
+simplified code maintenance.  Marked the corresponding stepper-specific
+user-callable routines as deprecated; these will be removed in a future major
+release.
+
+Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
+
+Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
+for users who wish to retain the current functionality.
+
 Updated the CMake variable `HIP_PLATFORM` default to `amd` as the previous
 default, `hcc`, is no longer recognized in ROCm 5.7.0 or newer. The new default
 is also valid in older version of ROCm (at least back to version 4.3.1).

benchmarks/diffusion_2D/main_arkode.cpp

@@ -245,49 +245,49 @@ int main(int argc, char* argv[])
     if (check_flag((void*)arkode_mem, "ARKStepCreate", 0)) { return 1; }
 
     // Specify tolerances
-    flag = ARKStepSStolerances(arkode_mem, uopts.rtol, uopts.atol);
-    if (check_flag(&flag, "ARKStepSStolerances", 1)) { return 1; }
+    flag = ARKodeSStolerances(arkode_mem, uopts.rtol, uopts.atol);
+    if (check_flag(&flag, "ARKodeSStolerances", 1)) { return 1; }
 
     // Attach user data
-    flag = ARKStepSetUserData(arkode_mem, (void*)&udata);
-    if (check_flag(&flag, "ARKStepSetUserData", 1)) { return 1; }
+    flag = ARKodeSetUserData(arkode_mem, (void*)&udata);
+    if (check_flag(&flag, "ARKodeSetUserData", 1)) { return 1; }
 
     // Attach linear solver
-    flag = ARKStepSetLinearSolver(arkode_mem, LS, A);
-    if (check_flag(&flag, "ARKStepSetLinearSolver", 1)) { return 1; }
+    flag = ARKodeSetLinearSolver(arkode_mem, LS, A);
+    if (check_flag(&flag, "ARKodeSetLinearSolver", 1)) { return 1; }
 
 #if defined(USE_SUPERLU_DIST)
     if (uopts.ls == "sludist")
     {
-      ARKStepSetJacFn(arkode_mem, diffusion_jac);
-      if (check_flag(&flag, "ARKStepSetJacFn", 1)) return 1;
+      ARKodeSetJacFn(arkode_mem, diffusion_jac);
+      if (check_flag(&flag, "ARKodeSetJacFn", 1)) return 1;
     }
 #endif
 
     if (uopts.preconditioning)
     {
       // Attach preconditioner
-      flag = ARKStepSetPreconditioner(arkode_mem, PSetup, PSolve);
-      if (check_flag(&flag, "ARKStepSetPreconditioner", 1)) { return 1; }
+      flag = ARKodeSetPreconditioner(arkode_mem, PSetup, PSolve);
+      if (check_flag(&flag, "ARKodeSetPreconditioner", 1)) { return 1; }
 
       // Set linear solver setup frequency (update preconditioner)
-      flag = ARKStepSetLSetupFrequency(arkode_mem, uopts.msbp);
-      if (check_flag(&flag, "ARKStepSetLSetupFrequency", 1)) { return 1; }
+      flag = ARKodeSetLSetupFrequency(arkode_mem, uopts.msbp);
+      if (check_flag(&flag, "ARKodeSetLSetupFrequency", 1)) { return 1; }
     }
 
     // Set linear solver tolerance factor
-    flag = ARKStepSetEpsLin(arkode_mem, uopts.epslin);
-    if (check_flag(&flag, "ARKStepSetEpsLin", 1)) { return 1; }
+    flag = ARKodeSetEpsLin(arkode_mem, uopts.epslin);
+    if (check_flag(&flag, "ARKodeSetEpsLin", 1)) { return 1; }
 
     // Select method order
-    flag = ARKStepSetOrder(arkode_mem, uopts.order);
-    if (check_flag(&flag, "ARKStepSetOrder", 1)) { return 1; }
+    flag = ARKodeSetOrder(arkode_mem, uopts.order);
+    if (check_flag(&flag, "ARKodeSetOrder", 1)) { return 1; }
 
     // Set fixed step size or adaptivity method
     if (uopts.hfixed > ZERO)
     {
-      flag = ARKStepSetFixedStep(arkode_mem, uopts.hfixed);
-      if (check_flag(&flag, "ARKStepSetFixedStep", 1)) { return 1; }
+      flag = ARKodeSetFixedStep(arkode_mem, uopts.hfixed);
+      if (check_flag(&flag, "ARKodeSetFixedStep", 1)) { return 1; }
     }
     else
     {
@@ -299,17 +299,17 @@ int main(int argc, char* argv[])
     // Specify linearly implicit non-time-dependent RHS
     if (uopts.linear)
     {
-      flag = ARKStepSetLinear(arkode_mem, 0);
-      if (check_flag(&flag, "ARKStepSetLinear", 1)) { return 1; }
+      flag = ARKodeSetLinear(arkode_mem, 0);
+      if (check_flag(&flag, "ARKodeSetLinear", 1)) { return 1; }
     }
 
     // Set max steps between outputs
-    flag = ARKStepSetMaxNumSteps(arkode_mem, uopts.maxsteps);
-    if (check_flag(&flag, "ARKStepSetMaxNumSteps", 1)) { return 1; }
+    flag = ARKodeSetMaxNumSteps(arkode_mem, uopts.maxsteps);
+    if (check_flag(&flag, "ARKodeSetMaxNumSteps", 1)) { return 1; }
 
     // Set stopping time
-    flag = ARKStepSetStopTime(arkode_mem, udata.tf);
-    if (check_flag(&flag, "ARKStepSetStopTime", 1)) { return 1; }
+    flag = ARKodeSetStopTime(arkode_mem, udata.tf);
+    if (check_flag(&flag, "ARKodeSetStopTime", 1)) { return 1; }
 
     // -----------------------
     // Loop over output times
@@ -341,8 +341,8 @@ int main(int argc, char* argv[])
       SUNDIALS_MARK_BEGIN(prof, "Evolve");
 
       // Evolve in time
-      flag = ARKStepEvolve(arkode_mem, tout, u, &t, stepmode);
-      if (check_flag(&flag, "ARKStepEvolve", 1)) { break; }
+      flag = ARKodeEvolve(arkode_mem, tout, u, &t, stepmode);
+      if (check_flag(&flag, "ARKodeEvolve", 1)) { break; }
 
       SUNDIALS_MARK_END(prof, "Evolve");
 
@@ -367,8 +367,8 @@ int main(int argc, char* argv[])
     if (outproc)
     {
       cout << "Final integrator statistics:" << endl;
-      flag = ARKStepPrintAllStats(arkode_mem, stdout, SUN_OUTPUTFORMAT_TABLE);
-      if (check_flag(&flag, "ARKStepPrintAllStats", 1)) { return 1; }
+      flag = ARKodePrintAllStats(arkode_mem, stdout, SUN_OUTPUTFORMAT_TABLE);
+      if (check_flag(&flag, "ARKodePrintAllStats", 1)) { return 1; }
     }
 
     // ---------
@@ -378,7 +378,7 @@ int main(int argc, char* argv[])
     // Free MPI Cartesian communicator
     MPI_Comm_free(&(udata.comm_c));
 
-    ARKStepFree(&arkode_mem);
+    ARKodeFree(&arkode_mem);
     SUNLinSolFree(LS);
 
     // Free the SuperLU_DIST structures (also frees user allocated arrays

doc/arkode/guide/source/Constants.rst

@@ -470,6 +470,9 @@ contains the ARKODE output constants.
    +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_CONTROLLER_ERR`         | -47  | An error with a SUNAdaptController object was encountered. |
    +-------------------------------------+------+------------------------------------------------------------+
+   | :index:`ARK_STEPPER_UNSUPPORTED`    | -48  | An operation was not supported by the current              |
+   |                                     |      | time-stepping module.                                      |
+   +-------------------------------------+------+------------------------------------------------------------+
    | :index:`ARK_UNRECOGNIZED_ERROR`     | -99  | An unknown error was encountered.                          |
    +-------------------------------------+------+------------------------------------------------------------+
    |                                                                                                         |

doc/arkode/guide/source/Introduction.rst

@@ -153,12 +153,12 @@ The structure of this document is as follows:
   ARKODE is :ref:`organized <ARKODE.Organization>`.
 
 * The largest section follows, providing a full account of how to use
-  ARKODE's time-stepping modules, :ref:`ARKStep <ARKODE.Usage.ARKStep>`,
-  :ref:`ERKStep <ARKODE.Usage.ERKStep>`, and :ref:`MRIStep <ARKODE.Usage.MRIStep>`,
-  within C and C++ applications.  This section then includes additional
-  information on how to use ARKODE from applications written in
-  :ref:`Fortran <SUNDIALS.Fortran>`, as well as information on how to
-  leverage :ref:`GPU accelerators within ARKODE <SUNDIALS.GPU>`.
+  ARKODE within C and C++ applications, including any instructions that are
+  specific to a given time-stepping modules, :ref:`ARKStep <ARKODE.Usage.ARKStep>`,
+  :ref:`ERKStep <ARKODE.Usage.ERKStep>`, or :ref:`MRIStep <ARKODE.Usage.MRIStep>`.
+  This section then includes additional information on how to use ARKODE from
+  applications written in :ref:`Fortran <SUNDIALS.Fortran>`, as well as information
+  on how to leverage :ref:`GPU accelerators within ARKODE <SUNDIALS.GPU>`.
 
 * A much smaller section follows, describing ARKODE's
   :ref:`Butcher table structure <ARKodeButcherTable>`, that is used by

doc/arkode/guide/source/Mathematics.rst

@@ -70,8 +70,8 @@ discussion of our choice of norms for measuring errors within various components
 of the solver.
 
 We then discuss the nonlinear and linear solver strategies used by
-ARKODE's time-stepping modules for solving implicit algebraic systems
-that arise in computing each stage and/or step:
+ARKODE for solving implicit algebraic systems that arise in computing each
+stage and/or step:
 :ref:`nonlinear solvers <ARKODE.Mathematics.Nonlinear>`,
 :ref:`linear solvers <ARKODE.Mathematics.Linear>`,
 :ref:`preconditioners <ARKODE.Mathematics.Preconditioning>`,
@@ -109,7 +109,7 @@ The choice of step size :math:`h_n` is determined by the time-stepping
 method (based on user-provided inputs, typically accuracy requirements).
 However, users may place minimum/maximum bounds on :math:`h_n` if desired.
 
-ARKODE's time stepping modules may be run in a variety of "modes":
+ARKODE may be run in a variety of "modes":
 
 * **NORMAL** -- The solver will take internal steps until it has just
   overtaken a user-specified output time, :math:`t_\text{out}`, in the
@@ -151,7 +151,7 @@ may be used.
 Interpolation
 ===============
 
-As mentioned above, the time-stepping modules in ARKODE support
+As mentioned above, the ARKODE supports
 interpolation of solutions :math:`y(t_\text{out})` and derivatives
 :math:`y^{(d)}(t_\text{out})`, where :math:`t_\text{out}` occurs
 within a completed time step from :math:`t_{n-1} \to t_n`.
@@ -162,13 +162,12 @@ ARKODE currently supports construction of polynomial interpolants
 :math:`p_q(t)` of polynomial degree up to :math:`q=5`, although
 users may select interpolants of lower degree.
 
-ARKODE provides two complementary interpolation approaches,
-both of which are accessible from any of the
-time-stepping modules: "Hermite" and "Lagrange".  The former approach
+ARKODE provides two complementary interpolation approaches:
+"Hermite" and "Lagrange".  The former approach
 has been included with ARKODE since its inception, and is more
-suitable for non-stiff problems; the latter is a new approach that is
-designed to provide increased accuracy when integrating stiff problems.
-Both are described in detail below.
+suitable for non-stiff problems; the latter is a more recent approach
+that is designed to provide increased accuracy when integrating stiff
+problems. Both are described in detail below.
 
 
 .. _ARKODE.Mathematics.Interpolation.Hermite:
@@ -565,7 +564,8 @@ form is used to compute a time step:
 #. Using compensated summation, set :math:`p_n = p_{n-1} + \Delta p_n, q_n = q_{n-1} + \Delta q_n`
 
 Since temporal error based adaptive time-stepping is known to ruin the
-conservation property :cite:p:`HaWa:06`,  SPRKStep employs a fixed time-step size.
+conservation property :cite:p:`HaWa:06`,  SPRKStep requires that ARKODE be run
+using a fixed time-step size.
 
 .. However, it is possible for a user to provide a
 .. problem-specific adaptivity controller such as the one described in :cite:p:`HaSo:05`.
@@ -1014,11 +1014,8 @@ information.  In this mode, all internal time step adaptivity is disabled:
    Fixed-step mode is currently required for the slow time scale in the MRIStep module.
 
 
-Additional information on this mode is provided in the sections
-:ref:`ARKStep Optional Inputs <ARKODE.Usage.ARKStep.OptionalInputs>`,
-:ref:`ERKStep Optional Inputs <ARKODE.Usage.ERKStep.OptionalInputs>`,
-:ref:`SPRKStep Optional Inputs <ARKODE.Usage.SPRKStep.OptionalInputs>`, and
-:ref:`MRIStep Optional Inputs <ARKODE.Usage.MRIStep.OptionalInputs>`.
+Additional information on this mode is provided in the section
+:ref:`ARKODE Optional Inputs <ARKODE.Usage.OptionalInputs>`.
 
 
 .. _ARKODE.Mathematics.AlgebraicSolvers:
@@ -1140,8 +1137,7 @@ Consider, for example, :eq:`ARKODE_Residual_MeqI` which implies
      :label: ARKODE_Implicit_Stage_Eval
 
 when :math:`z_i` is the exact root, and similar relations hold for non-identity
-mass matrices.  This optimization can be enabled by
-:c:func:`ARKStepSetDeduceImplicitRhs` and :c:func:`MRIStepSetDeduceImplicitRhs`
+mass matrices.  This optimization can be enabled by :c:func:`ARKodeSetDeduceImplicitRhs`
 with the second argument in either function set to SUNTRUE. Another factor to
 consider when using this option is the amplification of errors from the
 nonlinear solver to the stages. In :eq:`ARKODE_Implicit_Stage_Eval`, nonlinear
@@ -1948,10 +1944,9 @@ step (but zero linear solves with the system Jacobian).
 Rootfinding
 ===============
 
-All of the time-stepping modules in ARKODE also support a rootfinding
-feature.  This means that, while integrating the IVP :eq:`ARKODE_IVP`, these
-can also find the roots of a set of user-defined functions
-:math:`g_i(t,y)` that depend on :math:`t` and the solution vector
+ARKODE also supports a rootfinding feature, in that while integrating the
+IVP :eq:`ARKODE_IVP`, these can also find the roots of a set of user-defined
+functions :math:`g_i(t,y)` that depend on :math:`t` and the solution vector
 :math:`y = y(t)`. The number of these root functions is arbitrary, and
 if more than one :math:`g_i` is found to have a root in any given
 interval, the various root locations are found and reported in the
@@ -2065,8 +2060,8 @@ factor of 0.9 to cover the strict inequality case). If a step fails to satisfy
 the constraints 10 times (a value which may be modified by the user) within a
 step attempt, or fails with the minimum step size, then the integration is halted
 and an error is returned. In this case the user may need to employ other
-strategies as discussed in :numref:`ARKODE.Usage.ARKStep.Tolerances` and
-:numref:`ARKODE.Usage.ERKStep.Tolerances` to satisfy the inequality constraints.
+strategies as discussed in :numref:`ARKODE.Usage.Tolerances` to satisfy the
+inequality constraints.
 
 .. _ARKODE.Mathematics.Relaxation:
 
@@ -2130,5 +2125,4 @@ relaxation application and the step will is repeated with the step size reduced
 by :math:`\eta_\text{rf}`.
 
 For more information on utilizing relaxation Runge--Kutta methods, see
-:numref:`ARKODE.Usage.ERKStep.Relaxation` and
-:numref:`ARKODE.Usage.ARKStep.Relaxation`.
+:numref:`ARKODE.Usage.Relaxation`.

doc/arkode/guide/source/Organization.rst

@@ -25,29 +25,29 @@ knowledge of this structure is not necessary for its use.
 The overall organization of the ARKODE package is shown in
 :numref:`ARKODE.Organization.ARKODE.Figure`.  The central integration modules,
 implemented in the files ``arkode.h``, ``arkode_impl.h``, ``arkode_butcher.h``,
-``arkode.c``, ``arkode_arkstep.c`` , ``arkode_erkstep.c``, ``arkode_mristep.h``,
-and ``arkode_butcher.c``, deal with the evaluation of integration stages, the
-nonlinear solvers, estimation of the local truncation error, selection of step
-size, and interpolation to user output points, among other issues.  ARKODE
-supports SUNNonlinearSolver modules in either root-finding or fixed-point form
-(see section :numref:`SUNNonlinSol`) for any nonlinearly implicit problems that
-arise in computing each internal stage. When using Newton-based nonlinear
-solvers, or when using a non-identity mass matrix :math:`M\ne I`, ARKODE has
-flexibility in the choice of method used to solve the linear sub-systems that
-arise.  Therefore, for any user problem invoking the Newton solvers, or any user
-problem with :math:`M\ne I`, one (or more) of the linear system solver modules
-should be specified by the user; this/these are then invoked as needed during
-the integration process.
+``arkode.c``, ``arkode_arkstep.c`` , ``arkode_erkstep.c``, ``arkode_mristep.c``,
+``arkode_sprkstep.c``, and ``arkode_butcher.c``, deal with the evaluation of
+integration stages, the nonlinear solvers, estimation of the local truncation
+error, selection of step size, and interpolation to user output points, among
+other issues.  ARKODE supports SUNNonlinearSolver modules in either root-finding
+or fixed-point form (see section :numref:`SUNNonlinSol`) for any nonlinearly
+implicit problems that arise in computing each internal stage. When using
+Newton-based nonlinear solvers, or when using a non-identity mass matrix
+:math:`M\ne I`, ARKODE has flexibility in the choice of method used to solve the
+linear sub-systems that arise.  Therefore, for any user problem invoking the
+Newton solvers, or any user problem with :math:`M\ne I`, one (or more) of the
+linear system solver modules should be specified by the user; this/these are
+then invoked as needed during the integration process.
 
 .. _ARKODE.Organization.ARKODE.Figure:
 .. figure:: /figs/arkode/arkorg.png
    :align: center
 
    *ARKODE organization*: Overall structure of the ARKODE package.
-   Modules specific to ARKODE are the timesteppers (ARKODE), linear solver
-   interfaces (ARKLS), nonlinear solver interfaces (ARKNLS), and preconditioners
-   (ARKBANDPRE and ARKBBDPRE); all other items correspond to generic SUNDIALS
-   vector, matrix, and solver modules.
+   Modules specific to ARKODE are the core infrastructure and timesteppers
+   (ARKODE), linear solver interfaces (ARKLS), nonlinear solver interfaces
+   (ARKNLS), and preconditioners (ARKBANDPRE and ARKBBDPRE); all other items
+   correspond to generic SUNDIALS vector, matrix, and solver modules.
 
 For solving these linear systems, ARKODE's linear solver interface
 supports both direct and iterative linear solvers adhering to the