Skip to content

Commit bf3e552

Browse files
Add NEWS.md documenting v5.0.0 breaking changes
- Document breaking change in DAE initialization behavior - Provide clear migration guide for affected users - Explain available initialization algorithms - Include rationale for the breaking change - Add information about new ODE/SDE initialization support
1 parent 6473340 commit bf3e552

File tree

1 file changed

+89
-0
lines changed

1 file changed

+89
-0
lines changed

NEWS.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Sundials.jl NEWS
2+
3+
## v5.0.0
4+
5+
### Breaking Changes
6+
7+
#### DAE Initialization Algorithm Changes
8+
9+
The default initialization behavior for DAE problems has changed significantly. This is a **breaking change** that may affect existing code using IDA.
10+
11+
**Previous behavior:**
12+
- IDA would automatically attempt to compute consistent initial conditions by default
13+
- This automatic initialization could sometimes produce incorrect results without warning
14+
15+
**New behavior:**
16+
- The default is now validation-only mode that checks if provided initial conditions are consistent
17+
- If initial conditions are inconsistent, an error is raised with a clear message
18+
- Automatic initialization must be explicitly requested
19+
20+
**Migration Guide:**
21+
22+
If you have existing code that relies on automatic DAE initialization:
23+
24+
```julia
25+
# Old code (v4.x) - automatic initialization was implicit
26+
prob = DAEProblem(f, du0, u0, tspan, differential_vars = differential_vars)
27+
sol = solve(prob, IDA())
28+
```
29+
30+
You now have several options:
31+
32+
1. **Use automatic initialization explicitly (recommended for most users):**
33+
```julia
34+
using DiffEqBase: BrownFullBasicInit
35+
prob = DAEProblem(f, du0, u0, tspan, differential_vars = differential_vars)
36+
sol = solve(prob, IDA(), initializealg = BrownFullBasicInit())
37+
```
38+
39+
2. **Provide consistent initial conditions:**
40+
```julia
41+
# Ensure du0 and u0 satisfy f(du0, u0, p, t0) = 0
42+
prob = DAEProblem(f, du0, u0, tspan, differential_vars = differential_vars)
43+
sol = solve(prob, IDA()) # Will validate and proceed if consistent
44+
```
45+
46+
3. **For problems without differential_vars information:**
47+
```julia
48+
using DiffEqBase: ShampineCollocationInit
49+
prob = DAEProblem(f, du0, u0, tspan) # No differential_vars
50+
sol = solve(prob, IDA(), initializealg = ShampineCollocationInit())
51+
```
52+
53+
**Available initialization algorithms:**
54+
- `DefaultInit()` - Intelligently chooses initialization based on problem type (new default)
55+
- `BrownFullBasicInit()` - Brown's algorithm for index-1 DAEs (requires differential_vars)
56+
- `ShampineCollocationInit()` - Shampine's collocation method (works without differential_vars)
57+
- `CheckInit()` - Only validates initial conditions without modification
58+
59+
**Why this change was made:**
60+
- **Safety**: Silent automatic initialization could produce incorrect results
61+
- **Clarity**: Users now explicitly choose their initialization strategy
62+
- **Debugging**: Clearer error messages when initial conditions are inconsistent
63+
- **Performance**: Avoid unnecessary initialization computations when not needed
64+
65+
#### ODE/SDE Initialization Support
66+
67+
CVODE and ARKODE now support the `initializealg` parameter for parameter initialization compatibility with ModelingToolkit. This enables proper handling of problems with initialization requirements.
68+
69+
```julia
70+
# Now supported for ODE problems with initialization needs
71+
sol = solve(prob, CVODE_BDF(), initializealg = DefaultInit())
72+
```
73+
74+
### Features
75+
76+
- Added support for DiffEqBase initialization algorithms across all Sundials solvers
77+
- Improved callback handling to use callback-specific initialization algorithms
78+
- Enhanced error messages for DAE initialization failures
79+
80+
### Dependency Updates
81+
82+
- Minimum DiffEqBase version: 6.190.2
83+
- Added NonlinearSolveBase dependency for improved nonlinear solving
84+
- Added LinearSolve dependency for initialization support
85+
- Updated minimum SciMLBase version to 2.119.0
86+
87+
## Previous Versions
88+
89+
For changes in previous versions, see the git history and release notes on GitHub.

0 commit comments

Comments
 (0)