Added the roadmap
This commit is contained in:
Connor Johnstone
243
roadmap/features/02-vern7-method.md
Normal file
243
roadmap/features/02-vern7-method.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Feature: Vern7 (Verner 7th Order) Method
|
||||
|
||||
## Overview
|
||||
|
||||
Verner's 7th order method is a high-efficiency explicit Runge-Kutta method designed by Jim Verner. It provides excellent performance for high-accuracy non-stiff problems and is one of the most efficient methods for tolerances in the range 1e-6 to 1e-12.
|
||||
|
||||
**Key Characteristics:**
|
||||
- Order: 7(6) - 7th order solution with 6th order error estimate
|
||||
- Stages: 9
|
||||
- FSAL: Yes
|
||||
- Adaptive: Yes
|
||||
- Dense output: 7th order continuous extension
|
||||
- Optimized for minimal error coefficients
|
||||
|
||||
## Why This Feature Matters
|
||||
|
||||
- **High accuracy**: Essential for tight tolerance requirements (1e-8 to 1e-12)
|
||||
- **Efficiency**: More efficient than repeatedly refining lower-order methods
|
||||
- **Astronomical/orbital mechanics**: Common accuracy requirement
|
||||
- **Auto-switching foundation**: Needed for intelligent algorithm selection (pairs with Tsit5 for tolerance-based switching)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- None (can be implemented with current infrastructure)
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### Butcher Tableau
|
||||
|
||||
Vern7 has a 9-stage explicit RK tableau. The full coefficients are extensive (45 A-matrix entries).
|
||||
|
||||
Key properties:
|
||||
- c values: [0, 0.05, 0.1, 0.25, 0.5, 0.75, 1, 1, 1]
|
||||
- FSAL: k9 = k1 for next step
|
||||
- Optimized for small error coefficients
|
||||
|
||||
### Dense Output
|
||||
|
||||
7th order Hermite interpolation using all 9 stage values.
|
||||
|
||||
Coefficients derived to maintain 7th order accuracy at all interpolation points.
|
||||
|
||||
### Error Estimation
|
||||
|
||||
```
|
||||
err = ||u₇ - u₆|| / (atol + max(|u_n|, |u_{n+1}|) * rtol)
|
||||
```
|
||||
|
||||
Where the embedded 6th order method shares most stages with the 7th order method.
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Core Algorithm
|
||||
|
||||
- [ ] Define `Vern7` struct implementing `Integrator<D>` trait
|
||||
- [ ] Add tableau constants as static arrays
|
||||
- [ ] A matrix (lower triangular, 9x9, only 45 non-zero entries)
|
||||
- [ ] b vector (9 elements) for 7th order solution
|
||||
- [ ] b* vector (9 elements) for 6th order embedded solution
|
||||
- [ ] c vector (9 elements) for stage times
|
||||
- [ ] Add tolerance fields (a_tol, r_tol)
|
||||
- [ ] Add builder methods
|
||||
- [ ] Add optional `lazy` flag for lazy interpolation (future enhancement)
|
||||
|
||||
- [ ] Implement `step()` method
|
||||
- [ ] Pre-allocate k array: `Vec<SVector<f64, D>>` with capacity 9
|
||||
- [ ] Compute k1 = f(t, y)
|
||||
- [ ] Loop through stages 2-9:
|
||||
- [ ] Compute stage value using appropriate A-matrix entries
|
||||
- [ ] Evaluate ki = f(t + c[i]*h, y + h*sum(A[i,j]*kj))
|
||||
- [ ] Compute 7th order solution using b weights
|
||||
- [ ] Compute error using (b - b*) weights
|
||||
- [ ] Store all k values for dense output
|
||||
- [ ] Return (y_next, Some(error_norm), Some(k_stages))
|
||||
|
||||
- [ ] Implement `interpolate()` method
|
||||
- [ ] Calculate θ = (t - t_start) / (t_end - t_start)
|
||||
- [ ] Use 7th order interpolation polynomial with all 9 k values
|
||||
- [ ] Return interpolated state
|
||||
|
||||
- [ ] Implement constants
|
||||
- [ ] `ORDER = 7`
|
||||
- [ ] `STAGES = 9`
|
||||
- [ ] `ADAPTIVE = true`
|
||||
- [ ] `DENSE = true`
|
||||
|
||||
### Tableau Coefficients
|
||||
|
||||
The full Vern7 tableau is complex. Options:
|
||||
|
||||
1. **Extract from Julia source**:
|
||||
- File: `OrdinaryDiffEq.jl/lib/OrdinaryDiffEqVerner/src/verner_tableaus.jl`
|
||||
- Look for `Vern7ConstantCache` or similar
|
||||
|
||||
2. **Use Verner's original coefficients**:
|
||||
- Available in Verner's published papers
|
||||
- Verify rational arithmetic for exact representation
|
||||
|
||||
- [ ] Transcribe A matrix coefficients
|
||||
- [ ] Use Rust rational literals or high-precision floats
|
||||
- [ ] Add comments indicating matrix structure
|
||||
|
||||
- [ ] Transcribe b and b* vectors
|
||||
|
||||
- [ ] Transcribe c vector
|
||||
|
||||
- [ ] Transcribe dense output coefficients (binterp)
|
||||
|
||||
- [ ] Add test to verify tableau satisfies order conditions
|
||||
|
||||
### Integration with Problem
|
||||
|
||||
- [ ] Export Vern7 in prelude
|
||||
- [ ] Add to `integrator/mod.rs` module exports
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] **Convergence test**: Verify 7th order convergence
|
||||
- [ ] Use y' = -y with known solution
|
||||
- [ ] Run with tolerances [1e-8, 1e-9, 1e-10, 1e-11, 1e-12]
|
||||
- [ ] Plot log(error) vs log(tolerance)
|
||||
- [ ] Verify slope ≈ 7
|
||||
|
||||
- [ ] **High accuracy test**: Orbital mechanics
|
||||
- [ ] Two-body problem with known period
|
||||
- [ ] Integrate for 100 orbits
|
||||
- [ ] Verify position error < 1e-10 with rtol=1e-12
|
||||
|
||||
- [ ] **FSAL verification**:
|
||||
- [ ] Count function evaluations
|
||||
- [ ] Should be ~9n for n accepted steps (plus rejections)
|
||||
- [ ] With FSAL optimization active
|
||||
|
||||
- [ ] **Dense output accuracy**:
|
||||
- [ ] Verify 7th order interpolation between steps
|
||||
- [ ] Interpolate at 100 points between saved states
|
||||
- [ ] Error should scale with h^7
|
||||
|
||||
- [ ] **Comparison with DP5**:
|
||||
- [ ] Same problem, tight tolerance (1e-10)
|
||||
- [ ] Vern7 should take significantly fewer steps
|
||||
- [ ] Both should achieve accuracy, Vern7 should be faster
|
||||
|
||||
- [ ] **Comparison with Tsit5**:
|
||||
- [ ] Vern7 should be better at tight tolerances
|
||||
- [ ] Tsit5 may be competitive at moderate tolerances
|
||||
|
||||
### Benchmarking
|
||||
|
||||
- [ ] Add to benchmark suite
|
||||
- [ ] 3D Kepler problem (orbital mechanics)
|
||||
- [ ] Pleiades problem (N-body)
|
||||
- [ ] Compare wall-clock time vs DP5, Tsit5 at various tolerances
|
||||
|
||||
- [ ] Memory usage profiling
|
||||
- [ ] Verify efficient storage of 9 k-stages
|
||||
- [ ] Check for unnecessary allocations
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] Comprehensive docstring
|
||||
- [ ] When to use Vern7 (high accuracy, tight tolerances)
|
||||
- [ ] Performance characteristics
|
||||
- [ ] Comparison to other methods
|
||||
- [ ] Note: not suitable for stiff problems
|
||||
|
||||
- [ ] Usage example
|
||||
- [ ] High-precision orbital mechanics
|
||||
- [ ] Show tolerance selection guidance
|
||||
|
||||
- [ ] Add to README comparison table
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Standard Test: Pleiades Problem
|
||||
|
||||
The Pleiades problem (7-body gravitational system) is a standard benchmark:
|
||||
|
||||
```rust
|
||||
// 14 equations (7 bodies × 2D positions and velocities)
|
||||
// Known to require high accuracy
|
||||
// Non-stiff but requires many function evaluations with low-order methods
|
||||
```
|
||||
|
||||
Run from t=0 to t=3 with rtol=1e-10, atol=1e-12
|
||||
|
||||
Expected: Vern7 should complete in <2000 steps while DP5 might need >10000 steps
|
||||
|
||||
### Energy Conservation Test
|
||||
|
||||
For Hamiltonian systems, verify energy drift is minimal:
|
||||
- Simple pendulum or harmonic oscillator
|
||||
- Integrate for long time (1000 periods)
|
||||
- Measure energy drift at rtol=1e-10
|
||||
- Should be < 1e-9 relative error
|
||||
|
||||
## References
|
||||
|
||||
1. **Original Paper**:
|
||||
- Verner, J.H. (1978), "Explicit Runge-Kutta Methods with Estimates of the Local Truncation Error"
|
||||
- SIAM Journal on Numerical Analysis, Vol. 15, No. 4, pp. 772-790
|
||||
|
||||
2. **Coefficients**:
|
||||
- Verner's website: https://www.sfu.ca/~jverner/
|
||||
- Or extract from Julia implementation
|
||||
|
||||
3. **Julia Implementation**:
|
||||
- `OrdinaryDiffEq.jl/lib/OrdinaryDiffEqVerner/src/`
|
||||
- Files: `verner_tableaus.jl`, `verner_perform_step.jl`, `verner_caches.jl`
|
||||
|
||||
4. **Comparison Studies**:
|
||||
- Hairer, Nørsett, Wanner (2008), "Solving ODEs I", Section II.5
|
||||
- Performance comparisons with other high-order methods
|
||||
|
||||
## Complexity Estimate
|
||||
|
||||
**Effort**: Medium (6-10 hours)
|
||||
- Tableau transcription is tedious but straightforward
|
||||
- More stages than previous methods means more careful indexing
|
||||
- Dense output coefficients are complex
|
||||
- Extensive testing needed for verification
|
||||
|
||||
**Risk**: Medium
|
||||
- Getting tableau coefficients exactly right is crucial
|
||||
- Numerical precision matters more at 7th order
|
||||
- Need to verify against trusted reference
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Passes 7th order convergence test
|
||||
- [ ] Pleiades problem completes with expected step count
|
||||
- [ ] Energy conservation test shows minimal drift
|
||||
- [ ] FSAL optimization verified
|
||||
- [ ] Dense output achieves 7th order accuracy
|
||||
- [ ] Outperforms DP5 at tight tolerances in benchmarks
|
||||
- [ ] Documentation explains when to use Vern7
|
||||
- [ ] All tests pass with rtol down to 1e-14
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Lazy interpolation option (compute dense output only when needed)
|
||||
- [ ] Vern6, Vern8, Vern9 for complete family
|
||||
- [ ] Optimized implementation for small systems (compile-time specialization)
|
||||
Reference in New Issue
Block a user