differential-equations/roadmap/README.md

# Ordinary Differential Equations Library - Development Roadmap

This roadmap outlines the planned features for developing a comprehensive Rust-based ODE solver library, inspired by Julia's OrdinaryDiffEq.jl but adapted for Rust's strengths and idioms.

## Current Foundation

The library currently has:
- ✅ Dormand-Prince 4(5) adaptive explicit RK method with dense output
- ✅ Tsit5 explicit RK method with dense output
- ✅ PI step size controller
- ✅ Basic continuous callbacks with zero-crossing detection
- ✅ Solution interpolation interface
- ✅ Generic over array dimensions at compile-time
- ✅ Support for ordinary and second-order ODE problems

## Roadmap Organization

Features are organized into three tiers based on priority and dependencies:
- **Tier 1**: Essential features for general-purpose ODE solving
- **Tier 2**: Important features for robustness and broader applicability
- **Tier 3**: Advanced/specialized features for specific problem classes

Each feature below links to a detailed implementation plan in the `features/` directory.

---

## Tier 1: Essential Features

### Algorithms

- [x] **[BS3 (Bogacki-Shampine 3/2)](features/01-bs3-method.md)** ✅ COMPLETED
  - 3rd order explicit RK method with 2nd order error estimate
  - Good for moderate accuracy, lower cost than DP5
  - **Dependencies**: None
  - **Effort**: Small

- [x] **[Vern7 (Verner 7th order)](features/02-vern7-method.md)** ✅ COMPLETED
  - 7th order explicit RK method for high-accuracy non-stiff problems
  - Efficient for tight tolerances (2.7-8.8x faster than DP5 at 1e-10)
  - Full 7th order dense output with lazy computation
  - **Dependencies**: None
  - **Effort**: Medium
  - **Status**: All success criteria met, comprehensive benchmarks completed

- [ ] **[Rosenbrock23](features/03-rosenbrock23.md)**
  - L-stable 2nd/3rd order Rosenbrock-W method
  - First working stiff solver
  - **Dependencies**: Linear solver infrastructure, Jacobian computation
  - **Effort**: Large

### Controllers

- [x] **[PID Controller](features/04-pid-controller.md)** ✅ COMPLETED
  - Proportional-Integral-Derivative step size controller
  - Better stability than PI controller for difficult problems
  - **Dependencies**: None
  - **Effort**: Small

### Callbacks

- [ ] **[Discrete Callbacks](features/05-discrete-callbacks.md)**
  - Event detection based on conditions (not zero-crossings)
  - Useful for time-based events, iteration counts, etc.
  - **Dependencies**: None
  - **Effort**: Small

- [ ] **[CallbackSet](features/06-callback-set.md)**
  - Compose multiple callbacks with ordering
  - Essential for complex simulations
  - **Dependencies**: Discrete callbacks
  - **Effort**: Small

### Solution Interface

- [ ] **[Saveat Functionality](features/07-saveat.md)**
  - Save solution at specific timepoints
  - Dense vs sparse saving strategies
  - **Dependencies**: None
  - **Effort**: Medium

- [ ] **[Solution Derivatives](features/08-solution-derivatives.md)**
  - Access derivatives at any time point via interpolation
  - `solution.derivative(t)` interface
  - **Dependencies**: None
  - **Effort**: Small

---

## Tier 2: Important for Robustness

### Algorithms

- [ ] **[DP8 (Dormand-Prince 8th order)](features/09-dp8-method.md)**
  - 8th order explicit RK for very high accuracy
  - Complements Vern7 for algorithm selection
  - **Dependencies**: None
  - **Effort**: Medium

- [ ] **[FBDF (Fixed-leading-coefficient BDF)](features/10-fbdf-method.md)**
  - Multistep method for very stiff problems
  - More robust than Rosenbrock for some problem classes
  - **Dependencies**: Linear solver infrastructure, Nordsieck representation
  - **Effort**: Large

- [ ] **[Rodas4/Rodas5P](features/11-rodas-methods.md)**
  - Higher-order Rosenbrock methods (4th/5th order)
  - Better accuracy for stiff problems
  - **Dependencies**: Rosenbrock23
  - **Effort**: Medium

### Algorithm Selection

- [ ] **[Auto-Switching / Stiffness Detection](features/12-auto-switching.md)**
  - Automatic detection of stiffness
  - Switch between non-stiff and stiff solvers
  - Composite algorithm infrastructure
  - **Dependencies**: At least one stiff solver (Rosenbrock23 or FBDF)
  - **Effort**: Large

- [ ] **[Default Algorithm Selection](features/13-default-algorithm.md)**
  - Smart defaults based on problem characteristics
  - `solve(problem)` without specifying algorithm
  - **Dependencies**: Auto-switching, multiple algorithms
  - **Effort**: Medium

### Initialization

- [ ] **[Automatic Initial Step Size](features/14-initial-stepsize.md)**
  - Algorithm to determine good initial dt
  - Based on local Lipschitz estimate
  - **Dependencies**: None
  - **Effort**: Medium

### Callbacks

- [ ] **[PresetTimeCallback](features/15-preset-time-callback.md)**
  - Trigger callbacks at specific predetermined times
  - Important for time-varying forcing functions
  - **Dependencies**: Discrete callbacks
  - **Effort**: Small

- [ ] **[TerminateSteadyState](features/16-terminate-steady-state.md)**
  - Auto-detect when solution reaches steady state
  - Stop integration early
  - **Dependencies**: Discrete callbacks
  - **Effort**: Small

- [ ] **[SavingCallback](features/17-saving-callback.md)**
  - Custom saving logic beyond default
  - For memory-efficient large-scale simulations
  - **Dependencies**: CallbackSet
  - **Effort**: Small

### Infrastructure

- [ ] **[Linear Solver Infrastructure](features/18-linear-solver-infrastructure.md)**
  - Generic linear solver interface
  - Dense LU factorization
  - Foundation for implicit methods
  - **Dependencies**: None
  - **Effort**: Large

- [ ] **[Jacobian Computation](features/19-jacobian-computation.md)**
  - Finite difference Jacobians
  - Forward-mode automatic differentiation
  - Sparse Jacobian support
  - **Dependencies**: None
  - **Effort**: Large

---

## Tier 3: Advanced & Specialized

### Algorithms

- [ ] **[Low-Storage Runge-Kutta](features/20-low-storage-rk.md)**
  - 2N, 3N, 4N storage variants
  - Critical for large-scale problems
  - **Dependencies**: None
  - **Effort**: Medium

- [ ] **[SSP (Strong Stability Preserving) Methods](features/21-ssp-methods.md)**
  - SSPRK22, SSPRK33, SSPRK43, SSPRK53, etc.
  - For hyperbolic PDEs and method-of-lines
  - **Dependencies**: None
  - **Effort**: Medium

- [ ] **[Symplectic Integrators](features/22-symplectic-integrators.md)**
  - Velocity Verlet, Leapfrog, KahanLi6, KahanLi8
  - For Hamiltonian systems, preserves energy
  - **Dependencies**: Second-order ODE infrastructure (already exists)
  - **Effort**: Medium

- [ ] **[Verner Methods Suite](features/23-verner-methods.md)**
  - Vern6, Vern8, Vern9
  - Complete Verner family for different accuracy needs
  - **Dependencies**: Vern7
  - **Effort**: Medium

- [ ] **[SDIRK Methods](features/24-sdirk-methods.md)**
  - KenCarp3, KenCarp4, KenCarp5
  - Singly Diagonally Implicit RK for stiff problems
  - **Dependencies**: Linear solver infrastructure, nonlinear solver
  - **Effort**: Large

- [ ] **[Exponential Integrators](features/25-exponential-integrators.md)**
  - Exp4, EPIRK4, EXPRB53
  - For semi-linear stiff problems
  - **Dependencies**: Matrix exponential computation
  - **Effort**: Large

- [ ] **[Extrapolation Methods](features/26-extrapolation-methods.md)**
  - Implicit Euler/Midpoint with Richardson extrapolation
  - Adaptive order selection
  - **Dependencies**: Linear solver infrastructure
  - **Effort**: Large

- [ ] **[Stabilized Methods](features/27-stabilized-methods.md)**
  - ROCK2, ROCK4, RKC
  - For mildly stiff problems with large systems
  - **Dependencies**: None
  - **Effort**: Medium

### Controllers

- [ ] **[I Controller](features/28-i-controller.md)**
  - Basic integral controller
  - For completeness and testing
  - **Dependencies**: None
  - **Effort**: Small

- [ ] **[Predictive Controller](features/29-predictive-controller.md)**
  - Advanced controller with prediction
  - For challenging adaptive stepping scenarios
  - **Dependencies**: None
  - **Effort**: Medium

### Advanced Callbacks

- [ ] **[VectorContinuousCallback](features/30-vector-continuous-callback.md)**
  - Multiple simultaneous event detection
  - More efficient than multiple callbacks
  - **Dependencies**: CallbackSet
  - **Effort**: Medium

- [ ] **[PositiveDomain](features/31-positive-domain.md)**
  - Enforce positivity constraints
  - Important for physical systems
  - **Dependencies**: CallbackSet
  - **Effort**: Small

- [ ] **[ManifoldProjection](features/32-manifold-projection.md)**
  - Project solution onto constraint manifolds
  - For constrained mechanical systems
  - **Dependencies**: CallbackSet
  - **Effort**: Medium

### Infrastructure

- [ ] **[Nonlinear Solver Infrastructure](features/33-nonlinear-solver.md)**
  - Newton's method
  - Quasi-Newton methods
  - Generic nonlinear solver interface
  - **Dependencies**: Linear solver infrastructure
  - **Effort**: Large

- [ ] **[Krylov Linear Solvers](features/34-krylov-solvers.md)**
  - GMRES, BiCGStab
  - For large sparse systems
  - **Dependencies**: Linear solver infrastructure
  - **Effort**: Large

- [ ] **[Preconditioners](features/35-preconditioners.md)**
  - ILU, Jacobi, custom preconditioners
  - Accelerate Krylov methods
  - **Dependencies**: Krylov solvers
  - **Effort**: Large

### Performance & Optimization

- [ ] **[FSAL Optimization](features/36-fsal-optimization.md)**
  - First-Same-As-Last reuse
  - Reduce function evaluations
  - **Dependencies**: None
  - **Effort**: Small

- [ ] **[Custom Norms](features/37-custom-norms.md)**
  - User-definable error norms
  - L2, Linf, weighted norms
  - **Dependencies**: None
  - **Effort**: Small

- [ ] **[Step/Stage Limiting](features/38-step-stage-limiting.md)**
  - Limit state values during integration
  - For bounded problems
  - **Dependencies**: None
  - **Effort**: Small

---

## Implementation Notes

### General Principles

1. **Rust-first design**: Leverage Rust's type system, zero-cost abstractions, and safety guarantees
2. **Compile-time optimization**: Use const generics for array sizes where beneficial
3. **Trait-based abstraction**: Generic over array types, number types, and algorithm components
4. **Comprehensive testing**: Each feature needs convergence tests and comparison to known solutions
5. **Benchmarking**: Track performance as features are added

### Testing Strategy

Each algorithm implementation should include:
- **Convergence tests**: Verify order of accuracy
- **Correctness tests**: Compare to analytical solutions
- **Stiffness tests**: For stiff solvers, test on Van der Pol, Robertson, etc.
- **Callback tests**: Verify event detection accuracy
- **Regression tests**: Prevent performance degradation

### Documentation Requirements

- Public API documentation
- Algorithm descriptions and references
- Usage examples
- Performance characteristics

---

## Progress Tracking

Total Features: 38
- Tier 1: 8 features (3/8 complete) ✅
- Tier 2: 12 features (0/12 complete)
- Tier 3: 18 features (0/18 complete)

**Overall Progress: 7.9% (3/38 features complete)**

### Completed Features
1. ✅ BS3 (Bogacki-Shampine 3/2) - Tier 1 (2025-10-23)
2. ✅ Vern7 (Verner 7th order) - Tier 1 (2025-10-24)
3. ✅ PID Controller - Tier 1 (2025-10-24)

Last updated: 2025-10-24