Skip to content

Commit

Permalink
Feature: Add option to disable interpolation in ARKODE (#474)
Browse files Browse the repository at this point in the history 
Add support for disabling interpolated output in ARKODE steppers by
passing `ARK_INTERP_NONE` to `ARKodeSetInterpolantType`. Disabling
interpolation can reduce the memory footprint of an integrator by two or
more state vectors (depending on the interpolation type and degree)
which can be beneficial when interpolation is not needed e.g., when
integrating to a final time without output in between or using an
explicit fast time scale integrator with MRIStep.

When interpolation is disabled, rootfinding is not supported, implicit
methods must use the trivial predictor, interpolation at stop times
cannot be used, and calls to `ARKodeEvolve` in `ARK_NORMAL` mode will
return at or past the requested output time.

---------

Co-authored-by: Cody Balos <[email protected]>
Co-authored-by: Daniel R. Reynolds <[email protected]>
  • Loading branch information
@gardner48 @balos1 @drreynolds
3 people committed Jun 20, 2024
1 parent 8e1c543 commit 1fcd3b8
Show file tree
Hide file tree
Showing 31 changed files with 10,195 additions and 564 deletions.
95 changes: 64 additions & 31 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,20 @@

## Changes to SUNDIALS in release X.Y.Z

Fixed the runtime library installation path for windows systems. This fix changes the
default library installation path from `CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_LIBDIR` to
`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_BINDIR`.

Fixed conflicting `.lib` files between shared and static libs when using `MSVC` on Windows.
### Major Features

Fixed invalid `SUNDIALS_EXPORT` generated macro when building both shared and static libs.
Created shared user interface functions for ARKODE to allow more uniform control
over time-stepping algorithms, improved extensibility, and simplified code
maintenance. The corresponding stepper-specific user-callable functions are now
deprecated and will be removed in a future major release.

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 CMake infrastructure that enables externally maintained addons/plugins to
be *optionally* built with SUNDIALS. See the [Contributing
Guide](./CONTRIBUTING.md) for more details.

Added "Resize" capability, as well as missing `SetRootDirection` and
`SetNoInactiveRootWarn` functions, to ARKODE's SPRKStep time-stepping module.
### New Features and Enhancements

Deprecated `ARKStepSetOptimalParams` function; added instructions to user guide
for users who wish to retain the current functionality.
Added support for Kokkos Kernels v4.

Added the following Runge-Kutta Butcher tables
* `ARKODE_FORWARD_EULER_1_1`
Expand All @@ -40,37 +35,66 @@ Added the following MRI coupling tables
* `ARKODE_IMEX_MRI_GARK_TRAPEZOIDAL`
* `ARKODE_IMEX_MRI_GARK_MIDPOINT`

Users may now disable interpolated output in ARKODE by passing `ARK_INTERP_NONE`
to `ARKodeSetInterpolantType`. When interpolation is disabled, rootfinding is
not supported, implicit methods must use the trivial predictor (the default
option), and interpolation at stop times cannot be used (interpolating at stop
times is disabled by default). With interpolation disabled, calling
`ARKodeEvolve` in `ARK_NORMAL` mode will return at or past the requested output
time (setting a stop time may still be used to halt the integrator at a specific
time). Disabling interpolation will reduce the memory footprint of an integrator
by two or more state vectors (depending on the interpolant type and degree)
which can be beneficial when interpolation is not needed e.g., when integrating
to a final time without output in between or using an explicit fast time scale
integrator with an MRI method.

Added "Resize" capability to ARKODE's SPRKStep time-stepping module.

### Bug Fixes

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).

Fixed a bug in the HIP execution policies where `WARP_SIZE` would not be set
with ROCm 6.0.0 or newer.

Changed the CMake version compatibility mode for SUNDIALS to `AnyNewerVersion`
instead of `SameMajorVersion`. This fixes the issue seen
[here](https://github.com/AMReX-Codes/amrex/pull/3835).

Fixed a bug in some Fortran examples where `c_null_ptr` was passed as an argument
to a function pointer instead of `c_null_funptr`. This caused compilation issues
with the Cray Fortran compiler.
Fixed a CMake bug that caused an MPI linking error for our C++ examples in some
instances. Fixes [GitHub Issue
#464](https://github.com/LLNL/sundials/issues/464).

Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
from evolving the inner stepper.
Fixed the runtime library installation path for windows systems. This fix
changes the default library installation path from
`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_LIBDIR` to
`CMAKE_INSTALL_PREFIX/CMAKE_INSTALL_BINDIR`.

Added CMake infrastructure that enables externally maintained addons/plugins
to be *optionally* built with SUNDIALS. See the [Contributing Guide](./CONTRIBUTING.md)
for more details.
Fixed conflicting `.lib` files between shared and static libs when using `MSVC`
on Windows.

Added support for Kokkos Kernels v4.
Fixed invalid `SUNDIALS_EXPORT` generated macro when building both shared and
static libs.

Fixed a bug in some Fortran examples where `c_null_ptr` was passed as an
argument to a function pointer instead of `c_null_funptr`. This caused
compilation issues with the Cray Fortran compiler.

Fixed a bug in the HIP execution policies where `WARP_SIZE` would not be set
with ROCm 6.0.0 or newer.

Fixed a bug that caused error messages to be cut off in some cases. Fixes [GitHub Issue #461](https://github.com/LLNL/sundials/issues/461).
Fixed a bug that caused error messages to be cut off in some cases. Fixes
[GitHub Issue #461](https://github.com/LLNL/sundials/issues/461).

Fixed a memory leak when an error handler was added to a `SUNContext`. Fixes [GitHub Issue #466](https://github.com/LLNL/sundials/issues/466).
Fixed a memory leak when an error handler was added to a `SUNContext`. Fixes
[GitHub Issue #466](https://github.com/LLNL/sundials/issues/466).

Fixed a CMake bug that caused an MPI linking error for our C++ examples in some instances. Fixes [GitHub Issue #464](https://github.com/LLNL/sundials/issues/464).
Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
from evolving the inner stepper.

Added missing `SetRootDirection` and `SetNoInactiveRootWarn` functions to
ARKODE's SPRKStep time-stepping module.

Fixed a bug in `ARKodeSPRKTable_Create` where the coefficient arrays where not
Fixed a bug in `ARKodeSPRKTable_Create` where the coefficient arrays were not
allocated.

Fix bug on LLP64 platforms (like Windows 64-bit) where `KLU_INDEXTYPE` could be
Expand All @@ -79,6 +103,15 @@ Fix bug on LLP64 platforms (like Windows 64-bit) where `KLU_INDEXTYPE` could be
Check if size of `SuiteSparse_long` is 8 if the size of `sunindextype` is 8
when using KLU.

### Deprecation Notices

Numerous ARKODE stepper-specific functions are now deprecated in favor of
ARKODE-wide functions.

Deprecated the `ARKStepSetOptimalParams` function. Since this function does not have an
ARKODE-wide equivalent, instructions have been added to the user guide for how
to retain the current functionality using other user-callable functions.

## Changes to SUNDIALS in release v7.0.0

### Major Feature
Expand Down
2 changes: 2 additions & 0 deletions doc/arkode/guide/source/Constants.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ contains the ARKODE output constants.
+-----------------------------------------------+------------------------------------------------------------+
| **Interpolation module input constants** | |
+-----------------------------------------------+------------------------------------------------------------+
| :index:`ARK_INTERP_NONE` | Disables polynomial interpolation for dense output. |
+-----------------------------------------------+------------------------------------------------------------+
| :index:`ARK_INTERP_HERMITE` | Specifies use of the Hermite polynomial interpolation |
| | module (for non-stiff problems). |
+-----------------------------------------------+------------------------------------------------------------+
Expand Down
33 changes: 2 additions & 31 deletions doc/arkode/guide/source/Usage/ARKStep/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -552,39 +552,10 @@ Optional inputs for ARKStep
.. c:function:: int ARKStepSetInterpolantType(void* arkode_mem, int itype)
Specifies use of the Lagrange or Hermite interpolation modules (used for
dense output -- interpolation of solution output values and implicit
method predictors).
**Arguments:**
* *arkode_mem* -- pointer to the ARKStep memory block.
* *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
* *ARK_MEM_FAIL* if the interpolation module cannot be allocated
* *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
interpolation module has already been initialized
**Notes:**
The Hermite interpolation module is described in
:numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
This routine frees any previously-allocated interpolation module, and re-creates
one according to the specified argument. Thus any previous calls to
:c:func:`ARKStepSetInterpolantDegree()` will be nullified.
This routine may only be called *after* the call to :c:func:`ARKStepCreate`.
After the first call to :c:func:`ARKStepEvolve()` the interpolation type may
not be changed without first calling :c:func:`ARKStepReInit()`.
If this routine is not called, the Hermite interpolation module will be used.
.. deprecated:: x.y.z
Use :c:func:`ARKodeSetInterpolantType` instead.
This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
the documentation for that function instead.
.. c:function:: int ARKStepSetInterpolantDegree(void* arkode_mem, int degree)
Expand Down
33 changes: 2 additions & 31 deletions doc/arkode/guide/source/Usage/ERKStep/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -329,39 +329,10 @@ Optional inputs for ERKStep
.. c:function:: int ERKStepSetInterpolantType(void* arkode_mem, int itype)
Specifies use of the Lagrange or Hermite interpolation modules (used for
dense output -- interpolation of solution output values and implicit
method predictors).
**Arguments:**
* *arkode_mem* -- pointer to the ERKStep memory block.
* *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ERKStep memory is ``NULL``
* *ARK_MEM_FAIL* if the interpolation module cannot be allocated
* *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
interpolation module has already been initialized
**Notes:**
The Hermite interpolation module is described in
:numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
This routine frees any previously-allocated interpolation module, and re-creates
one according to the specified argument. Thus any previous calls to
:c:func:`ERKStepSetInterpolantDegree()` will be nullified.
This routine must be called *after* the call to :c:func:`ERKStepCreate`.
After the first call to :c:func:`ERKStepEvolve()` the interpolation type may
not be changed without first calling :c:func:`ERKStepReInit()`.
If this routine is not called, the Hermite interpolation module will be used.
.. deprecated:: x.y.z
Use :c:func:`ARKodeSetInterpolantType` instead.
This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
the documentation for that function instead.
Expand Down
38 changes: 2 additions & 36 deletions doc/arkode/guide/source/Usage/MRIStep/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -462,44 +462,10 @@ Optional inputs for MRIStep
.. c:function:: int MRIStepSetInterpolantType(void* arkode_mem, int itype)
Specifies use of the Lagrange or Hermite interpolation modules (used for
dense output -- interpolation of solution output values and implicit
method predictors).
**Arguments:**
* *arkode_mem* -- pointer to the MRIStep memory block.
* *itype* -- requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the MRIStep memory is ``NULL``
* *ARK_MEM_FAIL* if the interpolation module cannot be allocated
* *ARK_ILL_INPUT* if the *itype* argument is not recognized or the
interpolation module has already been initialized
**Notes:** The Hermite interpolation module is described in
:numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
This routine frees any previously-allocated interpolation module, and re-creates
one according to the specified argument. Thus any previous calls to
:c:func:`MRIStepSetInterpolantDegree()` will be nullified.
This routine must be called *after* the call to :c:func:`MRIStepCreate()`.
After the first call to :c:func:`MRIStepEvolve()` the interpolation type may
not be changed without first calling :c:func:`MRIStepReInit()`.
If this routine is not called, the Hermite interpolation module will be used.
.. deprecated:: x.y.z
Use :c:func:`ARKodeSetInterpolantType` instead.
This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
the documentation for that function instead.
Expand Down
36 changes: 2 additions & 34 deletions doc/arkode/guide/source/Usage/SPRKStep/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,42 +244,10 @@ Optional inputs for SPRKStep
.. c:function:: int SPRKStepSetInterpolantType(void* arkode_mem, int itype)
Specifies use of the Lagrange or Hermite interpolation modules (used for
dense output -- interpolation of solution output values and implicit
method predictors).
:param arkode_mem: pointer to the SPRKStep memory block.
:param itype: requested interpolant type (``ARK_INTERP_HERMITE`` or ``ARK_INTERP_LAGRANGE``)
:retval ARK_SUCCESS: if successful
:retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
:retval ARK_MEM_FAIL: if the interpolation module cannot be allocated
:retval ARK_ILL_INPUT: if the *itype* argument is not recognized or the
interpolation module has already been initialized
.. note::
The Hermite interpolation module is described in
:numref:`ARKODE.Mathematics.Interpolation.Hermite`, and the Lagrange interpolation module
is described in :numref:`ARKODE.Mathematics.Interpolation.Lagrange`.
This routine frees any previously-allocated interpolation module, and re-creates
one according to the specified argument. Thus any previous calls to
:c:func:`SPRKStepSetInterpolantDegree()` will be nullified.
This routine must be called *after* the call to :c:func:`SPRKStepCreate`.
After the first call to :c:func:`SPRKStepEvolve()` the interpolation type may
not be changed without first calling :c:func:`SPRKStepReInit()`.
If this routine is not called, the Lagrange interpolation module will be used.
Interpolated outputs may or may not conserve the Hamiltonian. Our testing
has shown that Lagrange interpolation typically performs well in this
regard, while Hermite interpolation does not.
.. deprecated:: x.y.z
Use :c:func:`ARKodeSetInterpolantType` instead.
This function is now a wrapper to :c:func:`ARKodeSetInterpolantType`, see
the documentation for that function instead.
.. c:function:: int SPRKStepSetInterpolantDegree(void* arkode_mem, int degree)
Expand Down
Loading

0 comments on commit 1fcd3b8

Please sign in to comment.