Skip to content

Commit e3034c5

Browse files
Update NEWS.md
1 parent 737d4e0 commit e3034c5

File tree

1 file changed

+49
-49
lines changed

1 file changed

+49
-49
lines changed

NEWS.md

Lines changed: 49 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,54 @@
44

55
### Breaking Changes
66

7+
#### Upgrade to Sundials v7
8+
9+
This release updates the underlying Sundials C library from v5 to v7, which introduces significant API changes. This is a **breaking change** for users directly using the low-level Sundials API.
10+
11+
**Key Changes:**
12+
13+
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.
14+
15+
2. **Memory management**: The new context-based approach improves thread safety and resource management.
16+
17+
**Migration Guide for Low-Level API Users:**
18+
19+
If you're using the low-level Sundials API directly (not through the DiffEq interface):
20+
21+
```julia
22+
# Old code (v4.x) - No context needed
23+
mem_ptr = CVodeCreate(CV_BDF)
24+
mem = Handle(mem_ptr)
25+
```
26+
27+
```julia
28+
# New code (v5.0) - Context required
29+
ctx_ptr = Ref{SUNContext}(C_NULL)
30+
SUNContext_Create(C_NULL, Base.unsafe_convert(Ptr{SUNContext}, ctx_ptr))
31+
ctx = ctx_ptr[]
32+
mem_ptr = CVodeCreate(CV_BDF, ctx) # Context passed as argument
33+
mem = Handle(mem_ptr)
34+
# ... use solver ...
35+
SUNContext_Free(ctx) # Clean up context when done
36+
```
37+
38+
**Automatic handling in high-level interface:**
39+
40+
If you're using the standard DiffEq interface (`solve(prob, CVODE_BDF())`), **no changes are needed**. The context is automatically managed internally:
41+
42+
```julia
43+
# This continues to work without changes
44+
sol = solve(prob, CVODE_BDF())
45+
```
46+
47+
**Functions affected by context requirement:**
48+
- All solver creation functions (`CVodeCreate`, `ARKStepCreate`, `IDACreate`, `KINCreate`)
49+
- All vector creation functions (`N_VNew_Serial`, etc.)
50+
- All matrix creation functions (`SUNDenseMatrix`, `SUNBandMatrix`, etc.)
51+
- All linear solver creation functions (`SUNLinSol_Dense`, etc.)
52+
53+
The context is automatically freed when the integrator is garbage collected through the `ContextHandle` mechanism.
54+
755
#### DAE Initialization Algorithm Changes
856

957
The default initialization behavior for DAE problems has changed significantly. This is a **breaking change** that may affect existing code using IDA.
@@ -62,54 +110,6 @@ sol = solve(prob, IDA(), initializealg = ShampineCollocationInit())
62110
- **Debugging**: Clearer error messages when initial conditions are inconsistent
63111
- **Performance**: Avoid unnecessary initialization computations when not needed
64112

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-
113113
#### ModelingToolkit Initialization Support
114114

115115
CVODE and ARKODE now support the `initializealg` parameter for parameter initialization compatibility with ModelingToolkit. This enables proper handling of problems with initialization requirements.
@@ -131,4 +131,4 @@ sol = solve(prob, CVODE_BDF()) # , initializealg = SciMLBase.OverrideInit()) don
131131
- Minimum DiffEqBase version: 6.190.2
132132
- Added NonlinearSolveBase dependency for improved nonlinear solving
133133
- Added LinearSolve dependency for initialization support
134-
- Updated minimum SciMLBase version to 2.119.0
134+
- Updated minimum SciMLBase version to 2.119.0

0 commit comments

Comments
 (0)