Releases: LLNL/sundials
SUNDIALS v5.0.0-dev.1
Summary
Our latest release, v5.0.0-dev.1, is a beta release of the next major SUNDIALS version and offers a preview of what is to come in SUNDIALS. The release includes new Fortran 2003 interface modules that provide Fortran users access to most of the SUNDIALS C API including the CVODE, ARKode, IDA, and KINSOL packages. The release also includes new linear solver interface functions, ARKLsLinSysFn and CVLsLinSysFn, which can be used as alternative methods for evaluating matrices for the linear systems M - gamma J and I - gamma J respectively, a new N_Vector implementation, NVECTOR_MPIPLUSX, which supports the MPI+X paradigm where X is a type of on-node parallelism such as CUDA, and several other improvements and bug fixes. We do not foresee any major API changes occurring between this release and v5.0.0, but various minor improvements are planned.
List of Changes
Several new functions were added to aid in creating custom NVECTOR,
SUNMATRIX, SUNLINEARSOLVER, and SUNNONLINEARSOLVER objects. The constructors
N_VNewEmpty(), SUNMatNewEmpty(), SUNLinSolNewEmpty(), and SUNNonlinSolNewEmpty()
allocate ``empty'' generic NVECTOR, SUNMATRIX, SUNLINEARSOLVER, and
SUNNONLINEARSOLVER objects respectively with the object's content pointer and
the function pointers in the operations structure initialized to NULL. When used
in the constructor for custom objects these functions will ease the introduction
of any new optional operations to the NVECTOR, SUNMATRIX, SUNLINEARSOLVER, or
SUNNONLINEARSOLVER APIs by ensuring only required operations need to be set.
Additionally, the functions N_VCopyOps(w, v) and SUNMatCopyOps(A, B) have been
added to copy the operation function pointers between vector and matrix objects
respectively. When used in clone routines for custom vector and matrix objects
these functions also will ease the introduction of any new optional operations
to the NVECTOR or SUNMATRIX APIs by ensuring all operations are copied when
cloning objects.
New linear solver interface functions ARKLsLinSysFn and CVLsLinSysFn were added
as alternative methods for evaluating the linear systems M - gamma J and
I - gamma J respectively.
Fixed a bug in the build system that prevented the PThreads NVECTOR module from
being built.
Fixed a bug in ARKStep where the mass matrix linear solver setup function was
not called in the Matrix-free case.
Fixed a minor bug in ARKStep where an incorrect flag is reported when an
error occurs in the mass matrix setup or Jacobian-vector product setup
functions.
Fixed a memory leak in the NVECTOR_PETSC clone function.
Fixed a memeory leaks in FARKODE, FCVODE, and FIDA when not using the default
nonlinear solver.
Fixed a bug in IDAQuadReInitB where an incorrect memory structure was passed to
IDAQuadReInit.
Added two new embedded ARK methods of orders 4 and 5 to ARKode (from
Kennedy & Carpenter, Appl. Numer. Math., 136:183--205, 2019).
The ManyVector NVECTOR module has been split into two versions: one
that requires MPI (MPIManyVector) and another that does not use
MPI at all (ManyVector). The associated example problems have
been similarly updated to reflect this new structure.
An additional NVECTOR implementation, NVECTOR_MPIPLUSX, was created to support
the MPI+X paradigm where X is a type of on-node parallelism (e.g. OpenMP, CUDA).
The implementation is accompanied by additions to user documentation and SUNDIALS
examples.
The *_MPICuda and *_MPIRaja functions were removed from the NVECTOR_CUDA and
NVECTOR_RAJA implementations respectively. Accordingly, the nvector_mpicuda.h,
nvector_mpiraja.h, libsundials_nvecmpicuda.lib, and libsundials_nvecmpicudaraja.lib
files have been removed. Users should use the NVECTOR_MPIPLUSX module coupled with
the NVECTOR_CUDA or NVECTOR_RAJA to replace the functionality. The necessary changes
are minimal and should require few code modifications.
New Fortran 2003 interfaces to ARKODE, IDA, KINSOL, all generic SUNDIALS types
(i.e. NVECTOR, SUNMATRIX, SUNLINEARSOLVER, SUNNONLINEARSOLVER), and the
NVECTOR_PARALLEL were added. These new interfaces were generated with SWIG-Fortran
and provide a user an idiomatic Fortran 2003 interface to most of the SUNDIALS C API.
The CVODE interface, and all module implementations with existing Fortran 2003 interfaces
were updated accordingly. See the section "Using for Fortran Applications" in
the appropriate user guide for more details on how to use the interfaces.
Removed extraneous calls to N_VMin() for simulations where
the scalar valued absolute tolerance, or all entries of the
vector-valued absolute tolerance array, are strictly positive. In
this scenario, CVODE(S), IDA(S) and ARKode will remove at least one
global reduction per time step.
v5.0.0-dev.0
Changes to SUNDIALS in release 5.0.0-dev.0
An additional N_Vector implementation, NVECTOR_MANYVECTOR, was
created to support flexible partitioning of solution data among
different processing elements (e.g., CPU + GPU) or for multi-physics
problems that couple distinct MPI-based simulations together (see
the NVECTOR_MANYVECTOR section in the user guides for more details).
This implementation is accompanied by additions to user documentation
and SUNDIALS examples.
Eleven new optional vector operations have been added to the N_Vector API to
support the new NVECTOR_MANYVECTOR implementation (see N_Vector chapter is the
user guides for more details). Two of the operations, N_VGetCommunicator and
N_VGetLength, must be implemented by subvectors that are combined to create an
NVECTOR_MANYVECTOR, but are not used outside of this context. The remaining nine
operations are optional local reduction operations intended to eliminate
unnecessary latency when performing vector reduction operations (norms, etc.) on
distributed memory systems. The optional local reduction vector operations are
N_VDotProdLocal, N_VMaxNormLocal, N_VMinLocal, N_VL1NormLocal, N_VWSqrSumLocal,
N_VWSqrSumMaskLocal, N_VInvTestLocal, N_VConstrMaskLocal, and
N_VMinQuotientLocal. If an N_Vector implementation defines any of the local
operations as NULL, then the NVECTOR_MANYVECTOR will call standard N_Vector
operations to complete the computation.
Additionally this release includes the following changes:
-
A new SUNMatrix and SUNLinearSolver implementation was added to facilitate
the use of the SuperLU_DIST library with SUNDIALS. -
A new operation, SUNMatMatvecSetup, was added to the SUNMatrix API. Users
who have implemented custom SUNMatrix modules will need to at least update
their code to set the corresponding ops structure member, matvecsetup, to NULL. -
The generic SUNMatrix API now defines error codes to be returned by SUNMatrix operations.
Operations which return an integer flag indiciating success/failure may return different
values than previously. -
The MRIStep module has been updated to support explicit, implicit, or IMEX
methods as the fast integrator using the ARKStep module. As a result some
function signatures have been changed including MRIStepCreate which now
takes an ARKStep memory structure for the fast integration as an input.
v4.1.0
Changes in minor release SUNDIALS v.4.1.0
An additional N_Vector implementation was added for Tpetra vector from Trilinos library to facilitate interoperability between SUNDIALS and Trilinos. This implementation is accompanied by additions to user documentation and SUNDIALS examples.
A bug was fixed where a nonlinear solver object could be freed twice in some use cases.
The EXAMPLES_ENABLE_RAJA CMake option has been removed. The optionEXAMPLES_ENABLE_CUDA enables all examples that use CUDA including the RAJA examples with a CUDA back end (if the RAJA NVECTOR is enabled).
The implementation header files (e.g. arkode_impl.h) are no longer installed. This means users who are directly manipulating package memory structures will need to update their code to use the package’s public API.
Python is no longer required to run make test and make test_install.
Fixed a bug in ARKodeButcherTable_Write when printing a Butcher table without an embedding.
v4.0.2
Changes in patch release SUNDIALS v.4.0.2
Added information about how to contribute to SUNDIALS as well as a contributor agreement.
Moved definitions of DLS and SPILS backwards compatibility functions to a source file. The symbols are now included in the appropriate package library, e.g. libsundials_cvode.lib.
v4.0.1
v4.0.0
Changes in major release SUNDIALS v.4.0.0
The direct and iterative linear solver interfaces in all SUNDIALS packages have been merged into unified linear solver interfaces for each package that support any valid SUNLINSOL module. This includes the previous DIRECT and ITERATIVE types and the new MATRIX_ITERATIVE type. Details regarding how SUNDIALS packages utilize linear solvers of each type as well as discussion regarding intended use cases for user-supplied SUNLINSOL implementations are included in the SUNLINSOL chapter of the user guides.
The unified interfaces are very similar to the previous DLS and SPILS interfaces. To minimize challenges in user migration to the unified linear solver interfaces, the previous DLS and SPILS routines for all packages may still be used; these will be deprecated in future releases, so we recommend that users migrate to the new names soon. Additionally, we note that Fortran users will need to enlarge their iout array of optional integer outputs, and update the indices that they query for certain linear-solver-related statistics.
The names of all constructor routines for SUNDIALS-provided SUNLinSol implementations have been updated to follow the naming convention SUNLinSol_* where * is the name of the linear solver e.g., Dense, KLU, SPGMR, PCG, etc. Solver-specific “set” routine names have been similarly standardized. To minimize challenges in user migration to the new names, the previous routine names may still be used; these will be deprecated in future releases, so we recommend that users migrate to the new names soon.
SUNDIALS integrators (ARKode, CVODE, CVODES, IDA, and IDAS) have been updated to utilize generic nonlinear solver modules through the SUNNONLINSOL API. This API will ease the addition of new nonlinear solver options and allow for external or user-supplied nonlinear solvers. The SUNNONLINSOL API and provided SUNNONLINSOL modules are described in a new user guide chapter and follow the same object oriented design and implementation used by the NVECTOR, SUNMATRIX, and SUNLINSOL modules.
With the introduction of SUNNonlinSol modules, the input parameter iter to CVodeCreate has been removed along with the function CVodeSetIterType and the constants CV_NEWTON and CV_FUNCTIONAL. Similarly, the ITMETH parameter has been removed from the Fortran interface function FCVMALLOC. Instead of specifying the nonlinear iteration type when creating the CVODE(S) memory structure, CVODE(S) uses the SUNNONLINSOL_NEWTON module implementation of a Newton iteration by default.For details on using a non-default or user-supplied nonlinear solver see the “Using CVODE[S] for …” chapters in the user guides. CVODE(S) functions for setting the nonlinear solver options (e.g., CVodeSetMaxNonlinIters) or getting nonlinear solver statistics (e.g., CVodeGetNumNonlinSolvIters) remain unchanged and internally call generic SUNNonlinSol functions as needed.
By default IDA(S) uses the SUNNONLINSOL_NEWTON module. Since IDA(S) previously only used an internal implementation of a Newton iteration no changes are required to user programs and functions for setting the nonlinear solver options (e.g., IDASetMaxNonlinIters) or getting nonlinear solver statistics (e.g., IDAGetNumNonlinSolvIters) remain unchanged and internally call generic SUNNonlinSol functions as needed. While SUNDIALS includes a fixed-point nonlinear solver module, it is not currently supported in IDA(S).For details on using a non-default or user-supplied nonlinear solver see the “Using IDA[S] for …” chapters in the user guides. Additionally, the example program idaRoberts_dns.c explicitly creates an attaches a SUNNONLINSOL_NEWTON object to demonstrate the process of creating and attaching a nonlinear solver module (note this is not necessary in general as IDA uses the SUNNONLINSOL_NEWTON module by default).
Three fused vector operations and seven vector array operations have been added to the NVECTOR API. These optional operations are disabled by default and may be activated by calling vector specific routines after creating an NVECTOR. See the NVECTOR chapter in the user guides for more information on the new operations.
Added a new NVECTOR (NVECTOR_OPENMPDEV) which leverages OpenMP 4.5+ device offloading.
Multiple updates to the CUDA NVECTOR were made:
- Changed the N_VMake_Cuda function to take a host data pointer and a device data pointer instead of an N_VectorContent_Cuda object.
- Changed N_VGetLength_Cuda to return the global vector length instead of the local vector length.
- Added N_VGetLocalLength_Cuda to return the local vector length.
- Added N_VGetMPIComm_Cuda to return the MPI communicator used.
- Removed the accessor functions in the namespace suncudavec.
- Added the ability to set the cudaStream_t used for execution of the CUDA NVECTOR kernels. See the function N_VSetCudaStreams_Cuda.
- Added N_VNewManaged_Cuda, N_VMakeManaged_Cuda, and N_VIsManagedMemory_Cuda functions to accommodate using managed memory with the CUDA NVECTOR.
Multiple updates to the RAJA NVECTOR were made:
- Changed N_VGetLength_Raja to return the global vector length instead of the local vector length.
- Added N_VGetLocalLength_Raja to return the local vector length.
- Added N_VGetMPIComm_Raja to return the MPI communicator used.
- Removed the accessor functions in the namespace sunrajavec.
The SUNBandMatrix constructor has been simplified to remove the storage upper bandwidth argument.
Two changes were made in the CVODE/CVODES/ARKODE initial step size algorithm:
- Fixed an efficiency bug where an extra call to the RHS function was made.
- Changed the behavior of the algorithm if the max-iterations case is hit. Before the algorithm would exit with the step size calculated on the penultimate iteration. Now it will exit with the step size calculated on the final iteration.
Fortran 2003 interfaces to CVODE, the fixed-point and Newton nonlinear solvers, the dense, band, KLU, PCG, SPBCGS, SPFGMR, SPGMR, and SPTFQMR linear solvers, and the serial, PThreads, and OpenMP NVECTORs have been added.
The ARKode library has been entirely rewritten to support a modular approach to one-step methods, which should allow for rapid research and development of novel integration methods without affecting existing solver functionality.
A new ARKode stepper, MRIStep, has been added for two rate explicit-explicit multirate infinitesimal step methods.
ARKode’s dense output infrastructure has been improved to support higher-degree Hermite polynomial interpolants (up to degree 5) over the last successful time step.