connor/differential-equations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/vern7
differential-equations/roadmap
History
Connor Johnstone 56458a721e Added energy conservation test
2025-10-24 14:04:51 -04:00
..
features
Added energy conservation test
2025-10-24 14:04:51 -04:00
FEATURE_TEMPLATES.md
Added the roadmap
2025-10-23 16:47:48 -04:00
GETTING_STARTED.md
Added the roadmap
2025-10-23 16:47:48 -04:00
README.md
Added energy conservation test
2025-10-24 14:04:51 -04:00

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

  • BS3 (Bogacki-Shampine 3/2) ✅ COMPLETED

    • 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) ✅ 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

    • L-stable 2nd/3rd order Rosenbrock-W method
    • First working stiff solver
    • Dependencies: Linear solver infrastructure, Jacobian computation
    • Effort: Large

Controllers

  • PID Controller
    • Proportional-Integral-Derivative step size controller
    • Better stability than PI controller for difficult problems
    • Dependencies: None
    • Effort: Small

Callbacks

  • Discrete Callbacks

    • Event detection based on conditions (not zero-crossings)
    • Useful for time-based events, iteration counts, etc.
    • Dependencies: None
    • Effort: Small

  • CallbackSet

    • Compose multiple callbacks with ordering
    • Essential for complex simulations
    • Dependencies: Discrete callbacks
    • Effort: Small

Solution Interface

  • Saveat Functionality

    • Save solution at specific timepoints
    • Dense vs sparse saving strategies
    • Dependencies: None
    • Effort: Medium

  • Solution Derivatives

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

    • 8th order explicit RK for very high accuracy
    • Complements Vern7 for algorithm selection
    • Dependencies: None
    • Effort: Medium

  • FBDF (Fixed-leading-coefficient BDF)

    • Multistep method for very stiff problems
    • More robust than Rosenbrock for some problem classes
    • Dependencies: Linear solver infrastructure, Nordsieck representation
    • Effort: Large

  • Rodas4/Rodas5P

    • Higher-order Rosenbrock methods (4th/5th order)
    • Better accuracy for stiff problems
    • Dependencies: Rosenbrock23
    • Effort: Medium

Algorithm Selection

  • Auto-Switching / Stiffness Detection

    • 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

    • Smart defaults based on problem characteristics
    • solve(problem) without specifying algorithm
    • Dependencies: Auto-switching, multiple algorithms
    • Effort: Medium

Initialization

  • Automatic Initial Step Size
    • Algorithm to determine good initial dt
    • Based on local Lipschitz estimate
    • Dependencies: None
    • Effort: Medium

Callbacks

  • PresetTimeCallback

    • Trigger callbacks at specific predetermined times
    • Important for time-varying forcing functions
    • Dependencies: Discrete callbacks
    • Effort: Small

  • TerminateSteadyState

    • Auto-detect when solution reaches steady state
    • Stop integration early
    • Dependencies: Discrete callbacks
    • Effort: Small

  • SavingCallback

    • Custom saving logic beyond default
    • For memory-efficient large-scale simulations
    • Dependencies: CallbackSet
    • Effort: Small

Infrastructure

  • Linear Solver Infrastructure

    • Generic linear solver interface
    • Dense LU factorization
    • Foundation for implicit methods
    • Dependencies: None
    • Effort: Large

  • Jacobian Computation

    • Finite difference Jacobians
    • Forward-mode automatic differentiation
    • Sparse Jacobian support
    • Dependencies: None
    • Effort: Large

Tier 3: Advanced & Specialized

Algorithms

  • Low-Storage Runge-Kutta

    • 2N, 3N, 4N storage variants
    • Critical for large-scale problems
    • Dependencies: None
    • Effort: Medium

  • SSP (Strong Stability Preserving) Methods

    • SSPRK22, SSPRK33, SSPRK43, SSPRK53, etc.
    • For hyperbolic PDEs and method-of-lines
    • Dependencies: None
    • Effort: Medium

  • Symplectic Integrators

    • Velocity Verlet, Leapfrog, KahanLi6, KahanLi8
    • For Hamiltonian systems, preserves energy
    • Dependencies: Second-order ODE infrastructure (already exists)
    • Effort: Medium

  • Verner Methods Suite

    • Vern6, Vern8, Vern9
    • Complete Verner family for different accuracy needs
    • Dependencies: Vern7
    • Effort: Medium

  • SDIRK Methods

    • KenCarp3, KenCarp4, KenCarp5
    • Singly Diagonally Implicit RK for stiff problems
    • Dependencies: Linear solver infrastructure, nonlinear solver
    • Effort: Large

  • Exponential Integrators

    • Exp4, EPIRK4, EXPRB53
    • For semi-linear stiff problems
    • Dependencies: Matrix exponential computation
    • Effort: Large

  • Extrapolation Methods

    • Implicit Euler/Midpoint with Richardson extrapolation
    • Adaptive order selection
    • Dependencies: Linear solver infrastructure
    • Effort: Large

  • Stabilized Methods

    • ROCK2, ROCK4, RKC
    • For mildly stiff problems with large systems
    • Dependencies: None
    • Effort: Medium

Controllers

  • I Controller

    • Basic integral controller
    • For completeness and testing
    • Dependencies: None
    • Effort: Small

  • Predictive Controller

    • Advanced controller with prediction
    • For challenging adaptive stepping scenarios
    • Dependencies: None
    • Effort: Medium

Advanced Callbacks

  • VectorContinuousCallback

    • Multiple simultaneous event detection
    • More efficient than multiple callbacks
    • Dependencies: CallbackSet
    • Effort: Medium

  • PositiveDomain

    • Enforce positivity constraints
    • Important for physical systems
    • Dependencies: CallbackSet
    • Effort: Small

  • ManifoldProjection

    • Project solution onto constraint manifolds
    • For constrained mechanical systems
    • Dependencies: CallbackSet
    • Effort: Medium

Infrastructure

  • Nonlinear Solver Infrastructure

    • Newton's method
    • Quasi-Newton methods
    • Generic nonlinear solver interface
    • Dependencies: Linear solver infrastructure
    • Effort: Large

  • Krylov Linear Solvers

    • GMRES, BiCGStab
    • For large sparse systems
    • Dependencies: Linear solver infrastructure
    • Effort: Large

  • Preconditioners

    • ILU, Jacobi, custom preconditioners
    • Accelerate Krylov methods
    • Dependencies: Krylov solvers
    • Effort: Large

Performance & Optimization

  • FSAL Optimization

    • First-Same-As-Last reuse
    • Reduce function evaluations
    • Dependencies: None
    • Effort: Small

  • Custom Norms

    • User-definable error norms
    • L2, Linf, weighted norms
    • Dependencies: None
    • Effort: Small

  • Step/Stage Limiting

    • 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 (2/8 complete) ✅
  • Tier 2: 12 features (0/12 complete)
  • Tier 3: 18 features (0/18 complete)

Overall Progress: 5.3% (2/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)

Last updated: 2025-10-24