differential-equations/roadmap/features/02-vern7-method.md

# 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)