Optional allocation of ARKODE internal data prior to ARKodeEvolve

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 Multiple minor updates were made to the ARKODE package.  We removed an extraneous
 copy of the output vector when using ARKODE in `ARK_ONE_STEP` mode.
+We added the function `ARKodeAllocateInternalData` to ARKODE to enable
+stage-related data allocation before the first call to `ARKodeEvolve` (but after
+all other optional input routines have been called), to support users who measure
+memory usage before beginning a simulation.
 The default number of stages for the SSP Runge-Kutta methods `ARKODE_LSRK_SSP_S_2`
 and `ARKODE_LSRK_SSP_S_3` in LSRKStep were changed from 10 and 9, respectively, to
 their minimum allowable values of 2 and 4. Users may revert to the previous values
@@ -22,8 +26,6 @@ stage is computed (`ARKodeSetPreprocessStepFn`, `ARKodeSetPostprocessStepFn`,
 should treat the state vector as read-only, otherwise all theoretical guarantees of
 solution accuracy and stability will be lost.
 
-Removed extraneous copy of output vector when using ARKODE in ``ARK_ONE_STEP`` mode.
-
 ### Bug Fixes
 
 Fixed a CMake bug where the SuperLU_MT interface would not be built and

bindings/sundials4py/arkode/arkode_generated.hpp

@@ -205,6 +205,9 @@ m.def("ARKodeSetFixedStep", ARKodeSetFixedStep, nb::arg("arkode_mem"),
 m.def("ARKodeSetStepDirection", ARKodeSetStepDirection, nb::arg("arkode_mem"),
       nb::arg("stepdir"));
 
+m.def("ARKodeAllocateInternalData", ARKodeAllocateInternalData,
+      nb::arg("arkode_mem"));
+
 m.def("ARKodeSetNonlinearSolver", ARKodeSetNonlinearSolver,
       nb::arg("arkode_mem"), nb::arg("NLS"));
 

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

@@ -5192,6 +5192,40 @@ Output all ARKODE solver parameters   :c:func:`ARKodeWriteParameters`
    .. versionadded:: 6.1.0
 
 
+.. _ARKODE.Usage.Preallocation:
+
+ARKODE data preallocation function
+----------------------------------
+
+Since the multi-stage structure of most ARKODE methods results in data
+requirements that depend on the number of stages, ARKODE generally defers
+allocation of stage-related internal data until the first call to
+:c:func:`ARKodeEvolve`.  However, in some cases the user may wish to
+preallocate this data earlier, for example to measure the memory footprint
+before beginning a calculation, or to check for allocation errors at an
+earlier time.  To request that that ARKODE preallocate all stage-related
+internal data before the first call to :c:func:`ARKodeEvolve`, the user
+may call the function :c:func:`ARKodeAllocateInternalData`.
+
+
+.. c:function:: int ARKodeAllocateInternalData(void* arkode_mem)
+
+   Optionally allocates stage-related internal data for the current ARKODE time-stepper module.
+
+   :param arkode_mem: pointer to the ARKODE memory block.
+
+   :retval ARK_SUCCESS: the function exited successfully.
+   :retval ARK_MEM_NULL:  ``arkode_mem`` was ``NULL``.
+   :retval ARK_MEM_FAIL:  a memory allocation failed.
+
+   .. warning::
+
+      This must be called **after** all other optional input routines have been called,
+      and **before** the first call to :c:func:`ARKodeEvolve`.  This routine should
+      be called at most once per ARKODE memory block.
+
+   .. versionadded:: x.y.z
+
 
 .. _ARKODE.Usage.Reset:
 

doc/shared/RecentChanges.rst

@@ -7,6 +7,10 @@
 
 Multiple minor updates were made to the ARKODE package.  We removed an extraneous
 copy of the output vector when using ARKODE in ``ARK_ONE_STEP`` mode.
+We added the function :c:func:`ARKodeAllocateInternalData` to ARKODE to enable
+stage-related data allocation before the first call to :c:func:`ARKodeEvolve`
+(but after all other optional input routines have been called), to support
+users who measure memory usage before beginning a simulation.
 The default number of stages for the SSP Runge-Kutta methods :c:enumerator:`ARKODE_LSRK_SSP_S_2`
 and :c:enumerator:`ARKODE_LSRK_SSP_S_3` in LSRKStep were changed from 10 and 9, respectively, to
 their minimum allowable values of 2 and 4. Users may revert to the previous values by calling
@@ -22,8 +26,6 @@ These are considered **advanced** functions, as they should treat the state vect
 read-only, otherwise all theoretical guarantees of solution accuracy and stability
 will be lost.
 
-Removed extraneous copy of output vector when using ARKODE in ``ARK_ONE_STEP`` mode.
-
 **Bug Fixes**
 
 Fixed a CMake bug where the SuperLU_MT interface would not be built and

examples/arkode/C_parallel/ark_diurnal_kry_bbd_p.out

@@ -8,57 +8,57 @@
 Preconditioner type is:  jpre = SUN_PREC_LEFT
 
 t = 7.20e+03   no. steps = 70   stepsize = 1.17e+02
-At bottom left:  c1, c2 =    1.047e+04    2.527e+11 
-At top right:    c1, c2 =    1.118e+04    2.700e+11 
+At bottom left:  c1, c2 =    1.047e+04    2.527e+11
+At top right:    c1, c2 =    1.118e+04    2.700e+11
 
 t = 1.44e+04   no. steps = 97   stepsize = 5.42e+02
-At bottom left:  c1, c2 =    6.659e+06    2.582e+11 
-At top right:    c1, c2 =    7.301e+06    2.833e+11 
+At bottom left:  c1, c2 =    6.659e+06    2.582e+11
+At top right:    c1, c2 =    7.301e+06    2.833e+11
 
 t = 2.16e+04   no. steps = 115   stepsize = 6.88e+02
-At bottom left:  c1, c2 =    2.665e+07    2.993e+11 
-At top right:    c1, c2 =    2.931e+07    3.313e+11 
+At bottom left:  c1, c2 =    2.665e+07    2.993e+11
+At top right:    c1, c2 =    2.931e+07    3.313e+11
 
 t = 2.88e+04   no. steps = 133   stepsize = 2.55e+02
-At bottom left:  c1, c2 =    8.702e+06    3.380e+11 
-At top right:    c1, c2 =    9.650e+06    3.751e+11 
+At bottom left:  c1, c2 =    8.702e+06    3.380e+11
+At top right:    c1, c2 =    9.650e+06    3.751e+11
 
 t = 3.60e+04   no. steps = 161   stepsize = 7.55e+01
-At bottom left:  c1, c2 =    1.404e+04    3.387e+11 
-At top right:    c1, c2 =    1.561e+04    3.765e+11 
+At bottom left:  c1, c2 =    1.404e+04    3.387e+11
+At top right:    c1, c2 =    1.561e+04    3.765e+11
 
 t = 4.32e+04   no. steps = 201   stepsize = 1.77e+03
-At bottom left:  c1, c2 =   -1.994e-07    3.382e+11 
-At top right:    c1, c2 =    4.533e-06    3.804e+11 
+At bottom left:  c1, c2 =   -1.994e-07    3.382e+11
+At top right:    c1, c2 =    4.533e-06    3.804e+11
 
 t = 5.04e+04   no. steps = 206   stepsize = 7.73e+02
-At bottom left:  c1, c2 =   -2.848e-08    3.358e+11 
-At top right:    c1, c2 =   -1.542e-07    3.864e+11 
+At bottom left:  c1, c2 =   -2.848e-08    3.358e+11
+At top right:    c1, c2 =   -1.542e-07    3.864e+11
 
 t = 5.76e+04   no. steps = 210   stepsize = 1.55e+03
-At bottom left:  c1, c2 =   -8.395e-07    3.320e+11 
-At top right:    c1, c2 =   -4.284e-07    3.909e+11 
+At bottom left:  c1, c2 =   -8.395e-07    3.320e+11
+At top right:    c1, c2 =   -4.284e-07    3.909e+11
 
 t = 6.48e+04   no. steps = 215   stepsize = 1.89e+03
-At bottom left:  c1, c2 =    1.234e-08    3.313e+11 
-At top right:    c1, c2 =    9.230e-08    3.963e+11 
+At bottom left:  c1, c2 =    1.234e-08    3.313e+11
+At top right:    c1, c2 =    9.230e-08    3.963e+11
 
 t = 7.20e+04   no. steps = 218   stepsize = 2.21e+03
-At bottom left:  c1, c2 =   -4.001e-08    3.330e+11 
-At top right:    c1, c2 =   -7.099e-06    4.039e+11 
+At bottom left:  c1, c2 =   -4.001e-08    3.330e+11
+At top right:    c1, c2 =   -7.099e-06    4.039e+11
 
 t = 7.92e+04   no. steps = 221   stepsize = 2.32e+03
-At bottom left:  c1, c2 =    3.713e-08    3.334e+11 
-At top right:    c1, c2 =   -3.992e-07    4.120e+11 
+At bottom left:  c1, c2 =    3.713e-08    3.334e+11
+At top right:    c1, c2 =   -3.992e-07    4.120e+11
 
 t = 8.64e+04   no. steps = 224   stepsize = 2.47e+03
-At bottom left:  c1, c2 =    3.734e-07    3.352e+11 
-At top right:    c1, c2 =    3.748e-07    4.163e+11 
+At bottom left:  c1, c2 =    3.734e-07    3.352e+11
+At top right:    c1, c2 =    3.748e-07    4.163e+11
 
 
-Final Statistics: 
+Final Statistics:
 
-lenrw   =  4118     leniw   =   291
+lenrw   =  4118     leniw   =   285
 lenrwls =  2455     leniwls =   126
 nst     =   224     nfe     =     0
 nfe     =  3315     nfels   =  6886
@@ -77,57 +77,57 @@ In ARKBBDPRE: real/integer local work space sizes = 1300, 192
 Preconditioner type is:  jpre = SUN_PREC_RIGHT
 
 t = 7.20e+03   no. steps = 69   stepsize = 1.17e+02
-At bottom left:  c1, c2 =    1.047e+04    2.527e+11 
-At top right:    c1, c2 =    1.118e+04    2.700e+11 
+At bottom left:  c1, c2 =    1.047e+04    2.527e+11
+At top right:    c1, c2 =    1.118e+04    2.700e+11
 
 t = 1.44e+04   no. steps = 96   stepsize = 5.40e+02
-At bottom left:  c1, c2 =    6.659e+06    2.582e+11 
-At top right:    c1, c2 =    7.301e+06    2.833e+11 
+At bottom left:  c1, c2 =    6.659e+06    2.582e+11
+At top right:    c1, c2 =    7.301e+06    2.833e+11
 
 t = 2.16e+04   no. steps = 114   stepsize = 6.89e+02
-At bottom left:  c1, c2 =    2.665e+07    2.993e+11 
-At top right:    c1, c2 =    2.931e+07    3.313e+11 
+At bottom left:  c1, c2 =    2.665e+07    2.993e+11
+At top right:    c1, c2 =    2.931e+07    3.313e+11
 
 t = 2.88e+04   no. steps = 131   stepsize = 1.93e+02
-At bottom left:  c1, c2 =    8.702e+06    3.380e+11 
-At top right:    c1, c2 =    9.650e+06    3.751e+11 
+At bottom left:  c1, c2 =    8.702e+06    3.380e+11
+At top right:    c1, c2 =    9.650e+06    3.751e+11
 
 t = 3.60e+04   no. steps = 159   stepsize = 7.48e+01
-At bottom left:  c1, c2 =    1.404e+04    3.387e+11 
-At top right:    c1, c2 =    1.561e+04    3.765e+11 
+At bottom left:  c1, c2 =    1.404e+04    3.387e+11
+At top right:    c1, c2 =    1.561e+04    3.765e+11
 
 t = 4.32e+04   no. steps = 199   stepsize = 1.75e+03
-At bottom left:  c1, c2 =   -1.508e-07    3.382e+11 
-At top right:    c1, c2 =   -1.680e-07    3.804e+11 
+At bottom left:  c1, c2 =   -1.508e-07    3.382e+11
+At top right:    c1, c2 =   -1.680e-07    3.804e+11
 
 t = 5.04e+04   no. steps = 203   stepsize = 1.28e+03
-At bottom left:  c1, c2 =    8.151e-09    3.358e+11 
-At top right:    c1, c2 =   -1.358e-08    3.864e+11 
+At bottom left:  c1, c2 =    8.151e-09    3.358e+11
+At top right:    c1, c2 =   -1.358e-08    3.864e+11
 
 t = 5.76e+04   no. steps = 208   stepsize = 9.65e+02
-At bottom left:  c1, c2 =    5.968e-08    3.320e+11 
-At top right:    c1, c2 =    1.041e-08    3.909e+11 
+At bottom left:  c1, c2 =    5.968e-08    3.320e+11
+At top right:    c1, c2 =    1.041e-08    3.909e+11
 
 t = 6.48e+04   no. steps = 213   stepsize = 1.90e+03
-At bottom left:  c1, c2 =   -4.322e-09    3.313e+11 
-At top right:    c1, c2 =    4.258e-10    3.963e+11 
+At bottom left:  c1, c2 =   -4.322e-09    3.313e+11
+At top right:    c1, c2 =    4.258e-10    3.963e+11
 
 t = 7.20e+04   no. steps = 216   stepsize = 2.21e+03
-At bottom left:  c1, c2 =    1.431e-07    3.330e+11 
-At top right:    c1, c2 =    1.210e-06    4.039e+11 
+At bottom left:  c1, c2 =    1.431e-07    3.330e+11
+At top right:    c1, c2 =    1.210e-06    4.039e+11
 
 t = 7.92e+04   no. steps = 219   stepsize = 2.32e+03
-At bottom left:  c1, c2 =    2.679e-08    3.334e+11 
-At top right:    c1, c2 =    1.594e-07    4.120e+11 
+At bottom left:  c1, c2 =    2.679e-08    3.334e+11
+At top right:    c1, c2 =    1.594e-07    4.120e+11
 
 t = 8.64e+04   no. steps = 222   stepsize = 2.47e+03
-At bottom left:  c1, c2 =    6.003e-08    3.352e+11 
-At top right:    c1, c2 =   -1.811e-07    4.163e+11 
+At bottom left:  c1, c2 =    6.003e-08    3.352e+11
+At top right:    c1, c2 =   -1.811e-07    4.163e+11
 
 
-Final Statistics: 
+Final Statistics:
 
-lenrw   =  4118     leniw   =   297
+lenrw   =  4118     leniw   =   285
 lenrwls =  2455     leniwls =   126
 nst     =   222     nfe     =     0
 nfe     =  3244     nfels   =  7604

examples/arkode/C_parallel/ark_diurnal_kry_p.out

@@ -2,62 +2,61 @@
 2-species diurnal advection-diffusion problem
 
 t = 7.20e+03   no. steps = 69   stepsize = 1.17e+02
-At bottom left:  c1, c2 =    1.047e+04    2.527e+11 
-At top right:    c1, c2 =    1.118e+04    2.700e+11 
+At bottom left:  c1, c2 =    1.047e+04    2.527e+11
+At top right:    c1, c2 =    1.118e+04    2.700e+11
 
 t = 1.44e+04   no. steps = 96   stepsize = 5.41e+02
-At bottom left:  c1, c2 =    6.659e+06    2.582e+11 
-At top right:    c1, c2 =    7.301e+06    2.833e+11 
+At bottom left:  c1, c2 =    6.659e+06    2.582e+11
+At top right:    c1, c2 =    7.301e+06    2.833e+11
 
 t = 2.16e+04   no. steps = 114   stepsize = 6.85e+02
-At bottom left:  c1, c2 =    2.665e+07    2.993e+11 
-At top right:    c1, c2 =    2.931e+07    3.313e+11 
+At bottom left:  c1, c2 =    2.665e+07    2.993e+11
+At top right:    c1, c2 =    2.931e+07    3.313e+11
 
 t = 2.88e+04   no. steps = 128   stepsize = 2.01e+02
-At bottom left:  c1, c2 =    8.702e+06    3.380e+11 
-At top right:    c1, c2 =    9.650e+06    3.751e+11 
+At bottom left:  c1, c2 =    8.702e+06    3.380e+11
+At top right:    c1, c2 =    9.650e+06    3.751e+11
 
 t = 3.60e+04   no. steps = 156   stepsize = 7.45e+01
-At bottom left:  c1, c2 =    1.404e+04    3.387e+11 
-At top right:    c1, c2 =    1.561e+04    3.765e+11 
+At bottom left:  c1, c2 =    1.404e+04    3.387e+11
+At top right:    c1, c2 =    1.561e+04    3.765e+11
 
 t = 4.32e+04   no. steps = 196   stepsize = 1.75e+03
-At bottom left:  c1, c2 =   -4.884e-08    3.382e+11 
-At top right:    c1, c2 =   -8.694e-07    3.804e+11 
+At bottom left:  c1, c2 =   -4.884e-08    3.382e+11
+At top right:    c1, c2 =   -8.694e-07    3.804e+11
 
 t = 5.04e+04   no. steps = 200   stepsize = 1.26e+03
-At bottom left:  c1, c2 =   -7.230e-09    3.358e+11 
-At top right:    c1, c2 =    3.094e-08    3.864e+11 
+At bottom left:  c1, c2 =   -7.230e-09    3.358e+11
+At top right:    c1, c2 =    3.094e-08    3.864e+11
 
 t = 5.76e+04   no. steps = 205   stepsize = 1.08e+03
-At bottom left:  c1, c2 =    4.422e-06    3.320e+11 
-At top right:    c1, c2 =   -2.623e-05    3.909e+11 
+At bottom left:  c1, c2 =    4.422e-06    3.320e+11
+At top right:    c1, c2 =   -2.623e-05    3.909e+11
 
 t = 6.48e+04   no. steps = 209   stepsize = 2.05e+03
-At bottom left:  c1, c2 =    1.105e-08    3.313e+11 
-At top right:    c1, c2 =    7.165e-08    3.963e+11 
+At bottom left:  c1, c2 =    1.105e-08    3.313e+11
+At top right:    c1, c2 =    7.165e-08    3.963e+11
 
 t = 7.20e+04   no. steps = 213   stepsize = 2.13e+03
-At bottom left:  c1, c2 =   -4.810e-06    3.330e+11 
-At top right:    c1, c2 =   -1.198e-04    4.039e+11 
+At bottom left:  c1, c2 =   -4.810e-06    3.330e+11
+At top right:    c1, c2 =   -1.198e-04    4.039e+11
 
 t = 7.92e+04   no. steps = 216   stepsize = 2.32e+03
-At bottom left:  c1, c2 =    7.856e-08    3.334e+11 
-At top right:    c1, c2 =    6.407e-07    4.120e+11 
+At bottom left:  c1, c2 =    7.856e-08    3.334e+11
+At top right:    c1, c2 =    6.407e-07    4.120e+11
 
 t = 8.64e+04   no. steps = 219   stepsize = 2.47e+03
-At bottom left:  c1, c2 =    1.878e-08    3.352e+11 
-At top right:    c1, c2 =    2.566e-08    4.163e+11 
+At bottom left:  c1, c2 =    1.878e-08    3.352e+11
+At top right:    c1, c2 =    2.566e-08    4.163e+11
 
 
-Final Statistics: 
+Final Statistics:
 
-lenrw   =  3518     leniw   =   267
+lenrw   =  3518     leniw   =   261
 lenrwls =  2455     leniwls =   126
 nst     =   219     nfe     =     0
 nfi     =  3215     nfels   =  6952
 nni     =  2012     nli     =  6952
 nsetups =    72     netf    =    21
 npe     =     6     nps     =  8886
 ncfn    =     2     ncfl    =   621
-