11# SUNDIALS Changelog
22
3- ## Changes to SUNDIALS in release X.X.X
3+ ## Changes to SUNDIALS in release 7.0.0-rc.1
44
5- The previously deprecated types ` realtype ` and ` booleantype ` were removed from ` sundials_types.h `
6- and replaced with ` sunrealtype ` and ` sunbooleantype ` . The deprecated names for these types
7- can be used by including the header file ` sundials_types_deprecated.h ` but will be fully removed in the
8- next major release.
5+ ⚠️ This is a release candidate.
6+
7+ ### Major Feature
98
10- ** Major feature**
119SUNDIALS now has more robust and uniform error handling. Non-release builds will
12- be built with additional error checking by default. See the "Error Handling"
10+ be built with additional error checking by default. See the
11+ [ Error Checking] ( https://sundials.readthedocs.io/en/latest/sundials/Errors_link.html )
1312section in the user guide for details.
1413
15- ** Deprecation notice**
16- The functions in ` sundials_math.h ` will be deprecated in the next release.
17-
18- ``` c
19- sunrealtype SUNRpowerI (sunrealtype base, int exponent);
20- sunrealtype SUNRpowerR(sunrealtype base, sunrealtype exponent);
21- sunbooleantype SUNRCompare(sunrealtype a, sunrealtype b);
22- sunbooleantype SUNRCompareTol(sunrealtype a, sunrealtype b, sunrealtype tol);
23- sunrealtype SUNStrToReal(const char* str);
24- ```
25-
26- Additionally, the following header files (and everything in them) will be deprecated -- users who
27- rely on these are recommended to transition to the corresponding `SUNMatrix` and `SUNLinearSolver`
28- modules:
29-
30- ```
31- sundials_direct.h
32- sundials_dense.h
33- sundials_band.h
34- ```
35-
36- **Breaking change**
37- The following functions have had their signature updated to ensure they can leverage
38- the new SUNDIALS error handling capabilties.
14+ ### Breaking Changes
15+
16+ #### Deprecated Types and Functions Removed
17+
18+ The previously deprecated types ` realtype ` and ` booleantype ` were removed from
19+ ` sundials_types.h ` and replaced with ` sunrealtype ` and ` sunbooleantype ` . The
20+ deprecated names for these types can be used by including the header file
21+ ` sundials_types_deprecated.h ` but will be fully removed in the next major
22+ release. Functions, types and header files that were previously deprecated have
23+ also been removed.
24+
25+ #### Error Handling Changes
26+
27+ With the addition of the new error handling capability, the ` *SetErrHandlerFn `
28+ and ` *SetErrFile ` functions in CVODE(S), IDA(S), ARKODE, and KINSOL have been
29+ removed. Users of these functions can use the functions
30+ ` SUNContext_PushErrHandler ` , and ` SUNLogger_SetErrorFilename ` instead. For
31+ further details see the
32+ [ Error Checking] ( https://sundials.readthedocs.io/en/latest/sundials/Errors_link.html )
33+ and
34+ [ Logging] ( https://sundials.readthedocs.io/en/latest/sundials/Logging_link.html )
35+ sections in the documentation.
36+
37+ In addition the following names/symbols were replaced by `` SUN_ERR_* `` codes:
38+
39+ | Removed | Replaced with `` SUNErrCode `` |
40+ | :-------------------------------| :----------------------------------|
41+ | ` SUNLS_SUCCESS ` | ` SUN_SUCCESS ` |
42+ | ` SUNLS_UNRECOV_FAILURE ` | no replacement (value was unused) |
43+ | ` SUNLS_MEM_NULL ` | ` SUN_ERR_ARG_CORRUPT ` |
44+ | ` SUNLS_ILL_INPUT ` | ` SUN_ERR_ARG_* ` |
45+ | ` SUNLS_MEM_FAIL ` | ` SUN_ERR_MEM_FAIL ` |
46+ | ` SUNLS_PACKAGE_FAIL_UNREC ` | ` SUN_ERR_EXT_FAIL ` |
47+ | ` SUNLS_VECTOROP_ERR ` | ` SUN_ERR_OP_FAIL ` |
48+ | ` SUN_NLS_SUCCESS ` | ` SUN_SUCCESS ` |
49+ | ` SUN_NLS_MEM_NULL ` | ` SUN_ERR_ARG_CORRUPT ` |
50+ | ` SUN_NLS_MEM_FAIL ` | ` SUN_ERR_MEM_FAIL ` |
51+ | ` SUN_NLS_ILL_INPUT ` | ` SUN_ERR_ARG_* ` |
52+ | ` SUN_NLS_VECTOROP_ERR ` | ` SUN_ERR_OP_FAIL ` |
53+ | ` SUN_NLS_EXT_FAIL ` | ` SUN_ERR_EXT_FAIL ` |
54+ | ` SUNMAT_SUCCESS ` | ` SUN_SUCCESS ` |
55+ | ` SUNMAT_ILL_INPUT ` | ` SUN_ERR_ARG_* ` |
56+ | ` SUNMAT_MEM_FAIL ` | ` SUN_ERR_MEM_FAIL ` |
57+ | ` SUNMAT_OPERATION_FAIL ` | ` SUN_ERR_OP_FAIL ` |
58+ | ` SUNMAT_MATVEC_SETUP_REQUIRED ` | ` SUN_ERR_OP_FAIL ` |
59+
60+ The following functions have had their signature updated to ensure they can
61+ leverage the new SUNDIALS error handling capabilities.
3962
4063``` c
4164// From sundials_futils.h
@@ -51,18 +74,18 @@ SUNMemoryHelper_Wrap
5174N_VNewVectorArray
5275```
5376
54- ** Breaking change**
77+ #### SUNComm Type Added
78+
5579We have replaced the use of a type-erased (i.e., ` void* ` ) pointer to a
5680communicator in place of ` MPI_Comm ` throughout the SUNDIALS API with a
5781` SUNComm ` , which is just a typedef to an ` int ` in builds without MPI
58- and a typedef to a ` MPI_Comm ` in builds with MPI. Here is what this means :
82+ and a typedef to a ` MPI_Comm ` in builds with MPI. As a result :
5983
6084- All users will need to update their codes because the call to
6185 ` SUNContext_Create ` now takes a ` SUNComm ` instead
6286 of type-erased pointer to a communicator. For non-MPI codes,
6387 pass ` SUN_COMM_NULL ` to the ` comm ` argument instead of
6488 ` NULL ` . For MPI codes, pass the ` MPI_Comm ` directly.
65- The required change should be doable with a find-and-replace.
6689
6790- The same change must be made for calls to
6891 ` SUNLogger_Create ` or ` SUNProfiler_Create ` .
@@ -78,45 +101,35 @@ The SUNLogger is now always MPI-aware if MPI is enabled in SUNDIALS and the
78101` SUNDIALS_LOGGING_ENABLE_MPI ` CMake option and macro definition were removed
79102accordingly.
80103
81- ** Breaking change**
82- Functions, types and header files that were previously deprecated have been
83- removed. In addition the following names/symbols were replaced by `` SUN_ERR_* ``
84- codes instead:
104+ #### SUNDIALS Core Library
85105
86- ```
87- SUNLS_SUCCESS --> SUN_SUCCESS
88- SUNLS_UNRECOV_FAILURE --> no replacement (this value was unused)
89- SUNLS_MEM_NULL --> SUN_ERR_ARG_CORRUPT
90- SUNLS_ILL_INPUT --> SUN_ERR_ARG_*
91- SUNLS_MEM_FAIL --> SUN_ERR_MEM_FAIL
92- SUNLS_PACKAGE_FAIL_UNREC --> SUN_ERR_EXT_FAIL
93- SUNLS_VECTOROP_ERR --> SUN_ERR_OP_FAIL
94- SUN_NLS_SUCCESS --> SUN_SUCCESS
95- SUN_NLS_MEM_NULL --> SUN_ERR_ARG_CORRUPT
96- SUN_NLS_MEM_FAIL --> SUN_ERR_MEM_FAIL
97- SUN_NLS_ILL_INPUT --> SUN_ERR_ARG_*
98- SUN_NLS_VECTOROP_ERR --> SUN_ERR_OP_FAIL
99- SUN_NLS_EXT_FAIL --> SUN_ERR_EXT_FAIL
100- SUNMAT_SUCCESS --> SUN_SUCCESS
101- SUNMAT_ILL_INPUT --> SUN_ERR_ARG_*
102- SUNMAT_MEM_FAIL --> SUN_ERR_MEM_FAIL
103- SUNMAT_OPERATION_FAIL --> SUN_ERR_OP_FAIL
104- SUNMAT_MATVEC_SETUP_REQUIRED --> SUN_ERR_OP_FAIL
106+ Users now need to link to ` sundials_core ` in addition to the libraries already
107+ linked to. This will be picked up automatically in projects that use the
108+ SUNDIALS CMake target. The library ` sundials_generic ` has been superseded by
109+ ` sundials_core ` and is no longer available. This fixes some duplicate symbol
110+ errors on Windows when linking to multiple SUNDIALS libraries.
111+
112+ ### Deprecation notice
113+
114+ The functions in ` sundials_math.h ` will be deprecated in the next release.
115+
116+ ``` c
117+ sunrealtype SUNRpowerI (sunrealtype base, int exponent);
118+ sunrealtype SUNRpowerR(sunrealtype base, sunrealtype exponent);
119+ sunbooleantype SUNRCompare(sunrealtype a, sunrealtype b);
120+ sunbooleantype SUNRCompareTol(sunrealtype a, sunrealtype b, sunrealtype tol);
121+ sunrealtype SUNStrToReal(const char* str);
105122```
106123
107- ** Breaking change**
108- Users now need to link to ` sundials_core ` in addition to the libraries already linked to.
109- This will be picked up automatically in projects that use the SUNDIALS CMake target.
110- The library ` sundials_generic ` has been superseded by ` sundials_core ` and is no longer available.
111- This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.
112-
113- ** Breaking change**
114- The ` *SetErrHandlerFn ` and ` *SetErrFile ` functions in CVODE(S), IDA(S), ARKODE and KINSOL have been
115- removed. Users of these functions can use the functions ` SUNContext_PushErrHandler ` , and
116- ` SUNLogger_SetErrorFilename ` instead. For further details see the [ Error
117- Checking] ( https://sundials.readthedocs.io/en/latest/sundials/Errors_link.html ) and
118- [ Logging] ( https://sundials.readthedocs.io/en/latest/sundials/Logging_link.html ) sections in the
119- documentation.
124+ Additionally, the following header files (and everything in them) will be
125+ deprecated -- users who rely on these are recommended to transition to the
126+ corresponding `SUNMatrix` and `SUNLinearSolver` modules:
127+
128+ ```c
129+ sundials_direct.h
130+ sundials_dense.h
131+ sundials_band.h
132+ ```
120133
121134## Changes to SUNDIALS in release 6.7.0
122135
0 commit comments