Skip to content

Commit 737d4e0

Browse files
Add documentation for Sundials v7 breaking changes
- Document SUNContext requirement for low-level API users - Provide migration guide showing old vs new context-based API - Clarify that high-level DiffEq interface users are unaffected - List all affected functions that now require context - Add Sundials_jll version update to dependency section
1 parent 6bfeb2a commit 737d4e0

File tree

1 file changed

+49
-0
lines changed

1 file changed

+49
-0
lines changed

NEWS.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,54 @@ sol = solve(prob, IDA(), initializealg = ShampineCollocationInit())
6262
- **Debugging**: Clearer error messages when initial conditions are inconsistent
6363
- **Performance**: Avoid unnecessary initialization computations when not needed
6464

65+
#### Upgrade to Sundials v7
66+
67+
This release updates the underlying Sundials C library from v6 to v7, which introduces significant API changes. This is a **breaking change** for users directly using the low-level Sundials API.
68+
69+
**Key Changes:**
70+
71+
1. **SUNContext requirement**: All Sundials objects now require a `SUNContext` object for creation. This context manages the Sundials environment and must be created before any solver objects.
72+
73+
2. **Memory management**: The new context-based approach improves thread safety and resource management.
74+
75+
**Migration Guide for Low-Level API Users:**
76+
77+
If you're using the low-level Sundials API directly (not through the DiffEq interface):
78+
79+
```julia
80+
# Old code (v4.x) - No context needed
81+
mem_ptr = CVodeCreate(CV_BDF)
82+
mem = Handle(mem_ptr)
83+
```
84+
85+
```julia
86+
# New code (v5.0) - Context required
87+
ctx_ptr = Ref{SUNContext}(C_NULL)
88+
SUNContext_Create(C_NULL, Base.unsafe_convert(Ptr{SUNContext}, ctx_ptr))
89+
ctx = ctx_ptr[]
90+
mem_ptr = CVodeCreate(CV_BDF, ctx) # Context passed as argument
91+
mem = Handle(mem_ptr)
92+
# ... use solver ...
93+
SUNContext_Free(ctx) # Clean up context when done
94+
```
95+
96+
**Automatic handling in high-level interface:**
97+
98+
If you're using the standard DiffEq interface (`solve(prob, CVODE_BDF())`), **no changes are needed**. The context is automatically managed internally:
99+
100+
```julia
101+
# This continues to work without changes
102+
sol = solve(prob, CVODE_BDF())
103+
```
104+
105+
**Functions affected by context requirement:**
106+
- All solver creation functions (`CVodeCreate`, `ARKStepCreate`, `IDACreate`, `KINCreate`)
107+
- All vector creation functions (`N_VNew_Serial`, etc.)
108+
- All matrix creation functions (`SUNDenseMatrix`, `SUNBandMatrix`, etc.)
109+
- All linear solver creation functions (`SUNLinSol_Dense`, etc.)
110+
111+
The context is automatically freed when the integrator is garbage collected through the `ContextHandle` mechanism.
112+
65113
#### ModelingToolkit Initialization Support
66114

67115
CVODE and ARKODE now support the `initializealg` parameter for parameter initialization compatibility with ModelingToolkit. This enables proper handling of problems with initialization requirements.
@@ -79,6 +127,7 @@ sol = solve(prob, CVODE_BDF()) # , initializealg = SciMLBase.OverrideInit()) don
79127

80128
### Dependency Updates
81129

130+
- **Sundials_jll**: Updated from v5.x to v7.4.1 (major version bump)
82131
- Minimum DiffEqBase version: 6.190.2
83132
- Added NonlinearSolveBase dependency for improved nonlinear solving
84133
- Added LinearSolve dependency for initialization support

0 commit comments

Comments
 (0)