Official development repository for SUNDIALS - a SUite of Nonlinear and DIfferential/ALgebraic equation Solvers. Pull requests are welcome for bug fixes and minor changes.
SUNDIALS now has more robust and uniform error handling. Non-release builds will be built with additional error checking by default. See the Error Checking section in the user guide for details.
SUNDIALS now requires using a compiler that supports a subset of the C99 standard. Note with the Microsoft C/C++ compiler the subset of C99 features utilized by SUNDIALS are available starting with Visual Studio 2015.
The previously deprecated types realtype and booleantype were removed from sundials_types.h and replaced with sunrealtype and sunbooleantype. The deprecated names for these types can be used by including the header file sundials_types_deprecated.h but will be fully removed in the next major release. Functions, types and header files that were previously deprecated have also been removed.
With the addition of the new error handling capability, the *SetErrHandlerFn and *SetErrFile functions in CVODE(S), IDA(S), ARKODE, and KINSOL have been removed. Users of these functions can use the functions SUNContext_PushErrHandler, and SUNLogger_SetErrorFilename instead. For further details see the Error Checking and Logging sections in the documentation.
In addition the following names/symbols were replaced by SUN_ERR_* codes:
| Removed | Replaced with SUNErrCode |
|---|---|
SUNLS_SUCCESS |
SUN_SUCCESS |
SUNLS_UNRECOV_FAILURE |
no replacement (value was unused) |
SUNLS_MEM_NULL |
SUN_ERR_ARG_CORRUPT |
SUNLS_ILL_INPUT |
SUN_ERR_ARG_* |
SUNLS_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUNLS_PACKAGE_FAIL_UNREC |
SUN_ERR_EXT_FAIL |
SUNLS_VECTOROP_ERR |
SUN_ERR_OP_FAIL |
SUN_NLS_SUCCESS |
SUN_SUCCESS |
SUN_NLS_MEM_NULL |
SUN_ERR_ARG_CORRUPT |
SUN_NLS_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUN_NLS_ILL_INPUT |
SUN_ERR_ARG_* |
SUN_NLS_VECTOROP_ERR |
SUN_ERR_OP_FAIL |
SUN_NLS_EXT_FAIL |
SUN_ERR_EXT_FAIL |
SUNMAT_SUCCESS |
SUN_SUCCESS |
SUNMAT_ILL_INPUT |
SUN_ERR_ARG_* |
SUNMAT_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUNMAT_OPERATION_FAIL |
SUN_ERR_OP_FAIL |
SUNMAT_MATVEC_SETUP_REQUIRED |
SUN_ERR_OP_FAIL |
The following functions have had their signature updated to ensure they can leverage the new SUNDIALS error handling capabilities.
// From sundials_futils.h
SUNDIALSFileOpen
SUNDIALSFileClose
// From sundials_memory.h
SUNMemorNewEmpty
SUNMemoryHelper_Alias
SUNMemoryHelper_Wrap
// From sundials_nvector.h
N_VNewVectorArray
We have replaced the use of a type-erased (i.e., void*) pointer to a communicator in place of MPI_Comm throughout the SUNDIALS API with a SUNComm, which is just a typedef to an int in builds without MPI and a typedef to a MPI_Comm in builds with MPI. As a result:
All users will need to update their codes because the call to SUNContext_Create now takes a SUNComm instead of type-erased pointer to a communicator. For non-MPI codes, pass SUN_COMM_NULL to the comm argument instead of NULL. For MPI codes, pass the MPI_Comm directly.
The same change must be made for calls to SUNLogger_Create or SUNProfiler_Create.
Some users will need to update their calls to N_VGetCommunicator, and update any custom N_Vector implementations that provide N_VGetCommunicator, since it now returns a SUNComm.
The change away from type-erased pointers for SUNComm fixes problems like the one described in GitHub Issue #275.
The SUNLogger is now always MPI-aware if MPI is enabled in SUNDIALS and the SUNDIALS_LOGGING_ENABLE_MPI CMake option and macro definition were removed accordingly.
Users now need to link to sundials_core in addition to the libraries already linked to. This will be picked up automatically in projects that use the SUNDIALS CMake target. The library sundials_generic has been superseded by sundials_core and is no longer available. This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.
We have streamlined the Fortran modules that need to be included by users by combining the SUNDIALS core into one Fortran module, fsundials_core_mod. Modules for implementations of the core APIs still exist (e.g., for the Dense linear solver there is fsunlinsol_dense_mod) as do the modules for the SUNDIALS packages (e.g., fcvode_mod). The following modules are the ones that have been consolidated into fsundials_core_mod:
fsundials_adaptcontroller_mod
fsundials_context_mod
fsundials_futils_mod
fsundials_linearsolver_mod
fsundials_logger_mod
fsundials_matrix_mod
fsundials_nonlinearsolver_mod
fsundials_nvector_mod
fsundials_profiler_mod
fsundials_types_mod
The functions in sundials_math.h will be deprecated in the next release.
sunrealtype SUNRpowerI(sunrealtype base, int exponent);
sunrealtype SUNRpowerR(sunrealtype base, sunrealtype exponent);
sunbooleantype SUNRCompare(sunrealtype a, sunrealtype b);
sunbooleantype SUNRCompareTol(sunrealtype a, sunrealtype b, sunrealtype tol);
sunrealtype SUNStrToReal(const char* str);
Additionally, the following header files (and everything in them) will be
deprecated -- users who rely on these are recommended to transition to the
corresponding SUNMatrix and SUNLinearSolver modules:
sundials_direct.h
sundials_dense.h
sundials_band.h
Fixed #329 so that C++20 aggregate initialization can be used.
Fixed integer overflow in the internal SUNDIALS hashmap. This resolves #409 and #249.
The CMAKE_BUILD_TYPE defaults to RelWithDebInfo mode now i.e., SUNDIALS will be built with optimizations and debugging symbols enabled by default. Previously the build type was unset by default so no optimization or debugging flags were set.
The advanced CMake options to override the inferred LAPACK name-mangling scheme have been updated from SUNDIALS_F77_FUNC_CASE and SUNDIALS_F77_FUNC_UNDERSCORES to SUNDIALS_LAPACK_CASE and SUNDIALS_LAPACK_UNDERSCORES, respectively.
Converted most previous Fortran 77 and 90 examples to use SUNDIALS' Fortran 2003 interface.
⚠️ This is a release candidate.
SUNDIALS now has more robust and uniform error handling. Non-release builds will be built with additional error checking by default. See the Error Checking section in the user guide for details.
The previously deprecated types realtype and booleantype were removed from sundials_types.h and replaced with sunrealtype and sunbooleantype. The deprecated names for these types can be used by including the header file sundials_types_deprecated.h but will be fully removed in the next major release. Functions, types and header files that were previously deprecated have also been removed.
With the addition of the new error handling capability, the *SetErrHandlerFn and *SetErrFile functions in CVODE(S), IDA(S), ARKODE, and KINSOL have been removed. Users of these functions can use the functions SUNContext_PushErrHandler, and SUNLogger_SetErrorFilename instead. For further details see the Error Checking and Logging sections in the documentation.
In addition the following names/symbols were replaced by SUN_ERR_* codes:
| Removed | Replaced with SUNErrCode |
|---|---|
SUNLS_SUCCESS |
SUN_SUCCESS |
SUNLS_UNRECOV_FAILURE |
no replacement (value was unused) |
SUNLS_MEM_NULL |
SUN_ERR_ARG_CORRUPT |
SUNLS_ILL_INPUT |
SUN_ERR_ARG_* |
SUNLS_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUNLS_PACKAGE_FAIL_UNREC |
SUN_ERR_EXT_FAIL |
SUNLS_VECTOROP_ERR |
SUN_ERR_OP_FAIL |
SUN_NLS_SUCCESS |
SUN_SUCCESS |
SUN_NLS_MEM_NULL |
SUN_ERR_ARG_CORRUPT |
SUN_NLS_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUN_NLS_ILL_INPUT |
SUN_ERR_ARG_* |
SUN_NLS_VECTOROP_ERR |
SUN_ERR_OP_FAIL |
SUN_NLS_EXT_FAIL |
SUN_ERR_EXT_FAIL |
SUNMAT_SUCCESS |
SUN_SUCCESS |
SUNMAT_ILL_INPUT |
SUN_ERR_ARG_* |
SUNMAT_MEM_FAIL |
SUN_ERR_MEM_FAIL |
SUNMAT_OPERATION_FAIL |
SUN_ERR_OP_FAIL |
SUNMAT_MATVEC_SETUP_REQUIRED |
SUN_ERR_OP_FAIL |
The following functions have had their signature updated to ensure they can leverage the new SUNDIALS error handling capabilities.
// From sundials_futils.h
SUNDIALSFileOpen
SUNDIALSFileClose
// From sundials_memory.h
SUNMemorNewEmpty
SUNMemoryHelper_Alias
SUNMemoryHelper_Wrap
// From sundials_nvector.h
N_VNewVectorArray
We have replaced the use of a type-erased (i.e., void*) pointer to a communicator in place of MPI_Comm throughout the SUNDIALS API with a SUNComm, which is just a typedef to an int in builds without MPI and a typedef to a MPI_Comm in builds with MPI. As a result:
All users will need to update their codes because the call to SUNContext_Create now takes a SUNComm instead of type-erased pointer to a communicator. For non-MPI codes, pass SUN_COMM_NULL to the comm argument instead of NULL. For MPI codes, pass the MPI_Comm directly.
The same change must be made for calls to SUNLogger_Create or SUNProfiler_Create.
Some users will need to update their calls to N_VGetCommunicator, and update any custom N_Vector implementations that provide N_VGetCommunicator, since it now returns a SUNComm.
The change away from type-erased pointers for SUNComm fixes problems like the one described in GitHub Issue #275.
The SUNLogger is now always MPI-aware if MPI is enabled in SUNDIALS and the SUNDIALS_LOGGING_ENABLE_MPI CMake option and macro definition were removed accordingly.
Users now need to link to sundials_core in addition to the libraries already linked to. This will be picked up automatically in projects that use the SUNDIALS CMake target. The library sundials_generic has been superseded by sundials_core and is no longer available. This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.
The functions in sundials_math.h will be deprecated in the next release.
sunrealtype SUNRpowerI(sunrealtype base, int exponent);
sunrealtype SUNRpowerR(sunrealtype base, sunrealtype exponent);
sunbooleantype SUNRCompare(sunrealtype a, sunrealtype b);
sunbooleantype SUNRCompareTol(sunrealtype a, sunrealtype b, sunrealtype tol);
sunrealtype SUNStrToReal(const char* str);
Additionally, the following header files (and everything in them) will be deprecated -- users who rely on these are recommended to transition to the corresponding SUNMatrix and SUNLinearSolver modules:
sundials_direct.h
sundials_dense.h
sundials_band.h
Added the SUNAdaptController base class, ported ARKODE's internal implementations of time step controllers into implementations of this class, and updated ARKODE to use these objects instead of its own implementations. Added ARKStepSetAdaptController and ERKStepSetAdaptController routines so that users can modify controller parameters, or even provide custom implementations.
Added the routines ARKStepSetAdaptivityAdjustment and ERKStepSetAdaptivityAdjustment, that allow users to adjust the value for the method order supplied to the temporal adaptivity controllers. The ARKODE default for this adjustment has been -1 since its initial release, but for some applications a value of 0 is more appropriate. Users who notice that their simulations encounter a large number of temporal error test failures may want to experiment with adjusting this value.
Added the third order ERK method ARKODE_SHU_OSHER_3_2_3, the fourth order ERK method ARKODE_SOFRONIOU_SPALETTA_5_3_4, the sixth order ERK method ARKODE_VERNER_9_5_6, the seventh order ERK method ARKODE_VERNER_10_6_7, the eighth order ERK method ARKODE_VERNER_13_7_8, and the ninth order ERK method ARKODE_VERNER_16_8_9.
ARKStep, ERKStep, MRIStep, and SPRKStep were updated to remove a potentially unnecessary right-hand side evaluation at the end of an integration. ARKStep was additionally updated to remove extra right-hand side evaluations when using an explicit method or an implicit method with an explicit first stage.
Improved computational complexity of SUNMatScaleAddI_Sparse from O(M*N) to O(NNZ).
Added Fortran support for the LAPACK dense SUNLinearSolver implementation.
Fixed a regression introduced by the stop time bug fix in v6.6.1 where ARKODE, CVODE, CVODES, IDA, and IDAS would return at the stop time rather than the requested output time if the stop time was reached in the same step in which the output time was passed.
Fixed a bug in ERKStep where methods with c[s-1] = 1 but a[s-1,j] != b[j] were incorrectly treated as having the first same as last (FSAL) property.
Fixed a bug in ARKODE where ARKStepSetInterpolateStopTime would return an interpolated solution at the stop time in some cases when interpolation was disabled.
Fixed a bug in ARKStepSetTableNum wherein it did not recognize ARKODE_ARK2_ERK_3_1_2 and ARKODE_ARK2_DIRK_3_1_2 as a valid additive Runge--Kutta Butcher table pair.
Fixed a bug in MRIStepCoupling_Write where explicit coupling tables were not written to the output file pointer.
The MRIStepInnerStepper class in MRIStep was updated to make supplying an MRIStepInnerFullRhsFn optional.
Fixed scaling bug in SUNMatScaleAddI_Sparse for non-square matrices.
Changed the SUNProfiler so that it does not rely on MPI_WTime in any case. This fixes GitHub Issue #312.
Fixed missing soversions in some SUNLinearSolver and SUNNonlinearSolver CMake targets.
Renamed some internal types in CVODES and IDAS to allow both packages to be built together in the same binary.
Fixed the build system support for MAGMA when using a NVIDIA HPC SDK installation of CUDA and fixed the targets used for rocBLAS and rocSPARSE.
Updated the Tpetra NVector interface to support Trilinos 14.
Fixed a memory leak when destroying a CUDA, HIP, SYCL, or system SUNMemoryHelper object.
Fixed a bug in ARKODE, CVODE, CVODES, IDA, and IDAS where the stop time may not be cleared when using normal mode if the requested output time is the same as the stop time. Additionally, with ARKODE, CVODE, and CVODES this fix removes an unnecessary interpolation of the solution at the stop time that could occur in this case.
A new time-stepping module, SPRKStep, was added to ARKODE. This time-stepper provides explicit symplectic partitioned Runge-Kutta methods up to order 10 for separable Hamiltonian systems.
Added support for relaxation Runge-Kutta methods to ERKStep and ARKStep in ARKODE.
Added the second order IMEX method from Giraldo, Kelly, and Constantinescu 2013 as the default second order IMEX method in ARKStep. The explicit table is given by ARKODE_ARK2_ERK_3_1_2 and the implicit table by ARKODE_ARK2_DIRK_3_1_2.
Updated CVODE, CVODES and ARKODE default behavior when returning the solution when the internal time has reached a user-specified stop time. Previously, the output solution was interpolated to the value of tstop; the default is now to copy the internal solution vector. Users who wish to revert to interpolation may call a new routine CVodeSetInterpolateStopTime, ARKStepSetInterpolateStopTime, ERKStepSetInterpolateStopTime, or MRIStepSetInterpolateStopTime.
A potential bug was fixed when using inequality constraint handling and calling ARKStepGetEstLocalErrors or ERKStepGetEstLocalErrors after a failed step in which an inequality constraint violation occurred. In this case, the values returned by ARKStepGetEstLocalErrors or ERKStepGetEstLocalErrors may have been invalid.
Updated the F2003 utility routines SUNDIALSFileOpen and SUNDIALSFileClose to support user specification of stdout and stderr strings for the output file names.
Added the functions ARKStepClearStopTime, ERKStepClearStopTime, MRIStepClearStopTime, CVodeClearStopTime, and IDAClearStopTime to disable a previously set stop time.
The default interpolant in ARKODE when using a first order method has been updated to a linear interpolant to ensure values obtained by the integrator are returned at the ends of the time interval. To restore the previous behavior of using a constant interpolant call ARKStepSetInterpolantDegree, ERKStepSetInterpolantDegree, or MRIStepSetInterpolantDegree and set the interpolant degree to zero before evolving the problem.
Fixed build errors when using SuperLU_DIST with ROCM enabled to target AMD GPUs.
Fixed compilation errors in some SYCL examples when using the icx compiler.
A new capability to keep track of memory allocations made through the SUNMemoryHelper classes has been added. Memory allocation stats can be accessed through the SUNMemoryHelper_GetAllocStats function. See the documentation for the SUNMemoryHelper classes for more details.
Added the functions ARKStepGetJac, ARKStepGetJacTime, ARKStepGetJacNumSteps, MRIStepGetJac, MRIStepGetJacTime, MRIStepGetJacNumSteps, CVodeGetJac, CVodeGetJacTime, CVodeGetJacNumSteps, IDAGetJac, IDAGetJacCj, IDAGetJacTime, IDAGetJacNumSteps, KINGetJac, KINGetJacNumIters to assist in debugging simulations utilizing a matrix-based linear solver.
Added support for CUDA 12.
Added support for the SYCL backend with RAJA 2022.x.y.
Fixed an underflow bug during root finding in ARKODE, CVODE, CVODES, IDA and IDAS.
Fixed an issue with finding oneMKL when using the icpx compiler with the -fsycl flag as the C++ compiler instead of dpcpp.
Fixed the shape of the arrays returned by FN_VGetArrayPointer functions as well as the FSUNDenseMatrix_Data, FSUNBandMatrix_Data, FSUNSparseMatrix_Data, FSUNSparseMatrix_IndexValues, and FSUNSparseMatrix_IndexPointers functions. Compiling and running code that uses the SUNDIALS Fortran interfaces with bounds checking will now work.
Fixed an implicit conversion error in the Butcher table for ESDIRK5(4)7L[2]SA2.
Fixed a bug with the Kokkos interfaces that would arise when using clang.
Fixed a compilation error with the Intel oneAPI 2022.2 Fortran compiler in the
Fortran 2003 interface test for the serial N_Vector.
Fixed a bug in the SUNLINSOL_LAPACKBAND and SUNLINSOL_LAPACKDENSE modules which would cause the tests to fail on some platforms.
CMake 3.18.0 or newer is now required for CUDA support.
A C++14 compliant compiler is now required for C++ based features and examples e.g., CUDA, HIP, RAJA, Trilinos, SuperLU_DIST, MAGMA, GINKGO, and KOKKOS.
Added support for GPU enabled SuperLU_DIST and SuperLU_DIST v8.x.x. Removed support for SuperLU_DIST v6.x.x or older. Fix mismatched definition and declaration bug in SuperLU_DIST matrix constructor.
Added support for the Ginkgo linear algebra
library. This support includes new SUNMatrix and SUNLinearSolver
implementations, see the SUNMATRIX_GINKGO and SUNLINEARSOLVER_GINKGO
sections in the documentation for more information.
Added new NVector, dense SUNMatrix, and dense SUNLinearSolver
implementations utilizing Kokkos Ecosystem for
performance portability, see the NVECTOR_KOKKOS, SUNMATRIX_KOKKOSDENSE and
SUNLINEARSOLVER_KOKKOSDENSE sections in the documentation for more
information.
Added the functions ARKStepSetTableName, ERKStepSetTableName,
MRIStepCoupling_LoadTableByName, ARKodeButcherTable_LoadDIRKByName, and
ARKodeButcherTable_LoadERKByName to load a table from a string.
Fixed a bug in the CUDA and HIP vectors where N_VMaxNorm would return the
minimum positive floating-point value for the zero vector.
Fixed memory leaks/out of bounds memory accesses in the ARKODE MRIStep module that could occur when attaching a coupling table after reinitialization with a different number of stages than originally selected.
Fixed a memory leak in CVODE and CVODES where the projection memory would not be
deallocated when calling CVodeFree.