Added the roadmap

2025-10-23 16:47:48 -04:00
parent 8d4aed4e84
commit e3788bf607
39 changed files with 3888 additions and 0 deletions
--- a/roadmap/README.md
+++ b/roadmap/README.md
@@ -0,0 +1,334 @@
+# 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
+
+- [ ] **[BS3 (Bogacki-Shampine 3/2)](features/01-bs3-method.md)**
+  - 3rd order explicit RK method with 2nd order error estimate
+  - Good for moderate accuracy, lower cost than DP5
+  - **Dependencies**: None
+  - **Effort**: Small
+
+- [ ] **[Vern7 (Verner 7th order)](features/02-vern7-method.md)**
+  - 7th order explicit RK method for high-accuracy non-stiff problems
+  - Efficient for tight tolerances
+  - **Dependencies**: None
+  - **Effort**: Medium
+
+- [ ] **[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
+
+- [ ] **[PID Controller](features/04-pid-controller.md)**
+  - 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 (0/8 complete)
+- Tier 2: 12 features (0/12 complete)
+- Tier 3: 18 features (0/18 complete)
+
+Last updated: 2025-01-XX