ordinary-diffeq/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
- ✅ Continuous callbacks with zero-crossing detection, whose effects can change
  the state, the parameters, or end the solution
- ✅ 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

- [x] **[Rosenbrock23](features/03-rosenbrock23.md)** ✅ COMPLETED
  - L-stable 2nd order Rosenbrock-W method with 3rd order error estimate
  - First working stiff solver for moderate accuracy stiff problems
  - Finite difference Jacobian computation
  - **Dependencies**: None
  - **Effort**: Large
  - **Status**: All success criteria met, matches Julia's implementation exactly

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

### API Ergonomics

- [x] **[Tolerances Trait](features/40-tolerances-trait.md)** ✅ COMPLETED
  - Move `a_tol` / `a_tol_full` / `r_tol` off the inherent impls into a trait, and
    add getters, so a generic `S` can set and read them
  - Raised by `astrokit`, which declared its own copy as a workaround
  - **Dependencies**: None
  - **Effort**: Small
  - **Status**: All four integrators implement `Tolerances`; no call site changed

- [x] **[Runtime Integrator Selection](features/41-runtime-integrator-selection.md)** ✅ COMPLETED
  - Structural facts move from associated constants to `&self` methods, so an
    enum can dispatch and an integrator can be chosen at runtime or named in a
    config file
  - **Dependencies**: None (pairs with Tolerances Trait)
  - **Effort**: Medium
  - **Status**: `Method` and `MethodName` added; benches measured at -0.7% to
    +0.4%, within criterion's noise threshold

### Callbacks

- [x] **[Callback Effects That Can Change the State](features/42-callback-effects.md)** ✅ COMPLETED
  - An effect's write to the state was overwritten by the step it was located in,
    so a callback could stop a solution but not change one
  - `effect(&mut self)`, termination at the crossing, both sides of a jump
    recorded, the controller reset across one, and a defined order for two events
    in one step
  - extended in 0.7.0 so a `Problem` can own a callback as well as borrow one,
    which is what a type that stores the problem needs
  - Raised by `astrokit`, which needs a Modified Rodrigues Parameter shadow set
    swap mid-propagation
  - **Dependencies**: None
  - **Effort**: Medium
  - **Status**: All success criteria met; benches unchanged within run-to-run drift

- [ ] **[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-functionality.md)**
  - Save solution at specific timepoints
  - Dense vs sparse saving strategies
  - **Dependencies**: None
  - **Effort**: Medium

- [ ] **Solution Derivatives** (no plan written yet)
  - 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)** (no plan written yet)
  - 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-rodas4-rodas5p-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-selection.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-automatic-initial-step-size.md)**
  - Algorithm to determine good initial dt
  - Based on local Lipschitz estimate
  - **Dependencies**: None
  - **Effort**: Medium

### Callbacks

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

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

- [ ] **[SavingCallback](features/17-savingcallback.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-runge-kutta.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-suite.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-vectorcontinuouscallback.md)**
  - Multiple simultaneous event detection
  - More efficient than multiple callbacks
  - **Dependencies**: CallbackSet
  - **Effort**: Medium

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

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

### Infrastructure

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

- [ ] **[Krylov Linear Solvers](features/34-krylov-linear-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

- [ ] **[Reduce Per-Step Allocation](features/39-per-step-allocation.md)**
  - Two heap allocations per accepted step (stage array, dense coefficients)
  - Against ~150 ns of arithmetic; matters only for cheap right-hand sides
  - **Dependencies**: None
  - **Effort**: Medium

---

## 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: 42
- Tier 1: 11 features (7/11 complete) ✅
- Tier 2: 11 features (0/11 complete)
- Tier 3: 20 features (0/20 complete)

**Overall Progress: 16.7% (7/42 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)
4. ✅ Rosenbrock23 - Tier 1 (2025-10-24)
5. ✅ Tolerances Trait - Tier 1 (2026-09-30)
6. ✅ Runtime Integrator Selection - Tier 1 (2026-09-30)
7. ✅ Callback Effects That Can Change the State - Tier 1 (2026-10-01)

Last updated: 2026-10-01