ordinary-diffeq/roadmap/GETTING_STARTED.md

Getting Started with the Roadmap

This guide helps you navigate the development roadmap for the Rust ODE library.

Roadmap Structure

roadmap/
├── README.md                  # Master overview with all features
├── GETTING_STARTED.md        # This file
├── FEATURE_TEMPLATES.md      # Brief summaries of features 6-38
└── features/
    ├── 01-bs3-method.md      # Detailed implementation plan (example)
    ├── 02-vern7-method.md    # Detailed implementation plan
    ├── 03-rosenbrock23.md    # Detailed implementation plan
    ├── 04-pid-controller.md  # Detailed implementation plan
    ├── 05-discrete-callbacks.md  # Detailed implementation plan
    ├── 06-callback-set.md    # Brief outline
    └── 12-auto-switching.md  # Detailed implementation plan
    └── ... (create detailed files as needed)

How to Use This Roadmap

1. Review the Master Plan

Start with README.md to see:

• All 38 planned features organized by tier
• Dependencies between features
• Current completion status
• Overall progress tracking

2. Choose Your Next Feature

Recommended Order for Beginners:

1. Start with Tier 1 features (essential)
2. Follow dependency chains
3. Mix difficulty levels (alternate hard and easy)

Suggested First 5 Features:

1. BS3 Method (feature #1) - Easy, builds confidence
2. PID Controller (feature #4) - Easy, immediate value
3. Discrete Callbacks (feature #5) - Easy, useful capability
4. Vern7 (feature #2) - Medium, important algorithm
5. Linear Solver Infrastructure (feature #18) - Hard but foundational

3. Read the Detailed Feature File

Each detailed feature file contains:

• Overview: Quick introduction
• Why It Matters: Motivation
• Dependencies: What you need first
• Implementation Approach: Algorithm details
• Implementation Tasks: Detailed checklist
• Testing Requirements: How to verify it works
• References: Where to learn more
• Complexity Estimate: Time and difficulty
• Success Criteria: Definition of done

4. Implement the Feature

Follow the detailed task checklist:

• Read references and understand algorithm
• Implement core algorithm
• Write tests
• Document
• Benchmark
• Check off tasks as you complete them

5. Update the Roadmap

When you complete a feature:

1. Check the box in README.md
2. Update completion statistics
3. Note any lessons learned or deviations from plan

Current State (Baseline)

Your library already has:

• ✅ Dormand-Prince 4(5) with dense output
• ✅ Tsit5 with dense output
• ✅ PI Controller
• ✅ Continuous callbacks with zero-crossing detection
• ✅ Solution interpolation interface
• ✅ Generic over compile-time array dimensions
• ✅ Support for second-order ODE problems

This is a solid foundation! The roadmap builds on this.

Recommended Development Path

Phase 1: Core Algorithm Diversity (Tier 1)

Goal: Give users algorithm choices

1. BS3 - Easy, quick win
2. Vern7 - High accuracy option
3. Build linear solver infrastructure
4. Rosenbrock23 - First stiff solver
5. PID Controller - Better adaptive stepping
6. Discrete Callbacks - More event types

Milestone: Can handle both non-stiff and stiff problems efficiently.

Phase 2: Robustness & Automation (Tier 2)

Goal: Make the library production-ready

7. Auto-switching/stiffness detection
8. Automatic initial step size
9. More Rosenbrock methods (Rodas4)
10. BDF method
11. CallbackSet and advanced callbacks
12. Saveat functionality

Milestone: Library can solve most problems automatically with minimal user input.

Phase 3: Specialization & Performance (Tier 3)

Goal: Optimize for specific problem classes

13. Low-storage RK for large systems
14. Symplectic integrators for Hamiltonian systems
15. SSP methods for hyperbolic PDEs
16. Verner suite completion
17. Advanced linear/nonlinear solvers
18. Performance optimizations (FSAL, custom norms)

Milestone: Best-in-class performance for specialized problem types.

Development Tips

Checks, and the Hooks That Run Them

The tree is rustfmt-clean, clippy-clean under -D warnings, and builds its docs without warnings. All three stay that way, and a pre-existing warning is not an exemption — fix it or mark it deliberately, as the Butcher tableaux are marked #[rustfmt::skip] so rustfmt leaves their hand alignment alone.

The hooks in hooks/ run them. Git does not track where it looks for hooks, so each clone needs one command:

git config core.hooksPath hooks

pre-commit is cargo fmt --check, cargo clippy --all-targets -- -D warnings and cargo test --lib, about a second between them on a warm tree. pre-push adds the full cargo test and cargo doc --no-deps, which cost around 25 seconds — the doctests are slow because each one links its own binary, and they matter because the readme is the crate's front page and its examples are compiled.

Testing Strategy

Every feature should have:

1. Convergence test: Verify order of accuracy
2. Correctness test: Compare to known solutions
3. Edge case tests: Boundary conditions, error handling
4. Benchmark: Performance measurement

Reference Material

When implementing a feature:

1. Read the Julia implementation for guidance
2. Check original papers for algorithm details
3. Verify tableau/coefficients from authoritative sources
4. Test against reference solutions from DiffEqDevDocs

Common Pitfalls

• Don't skip testing: Numerical bugs are subtle
• Verify tableau coefficients: Transcription errors are common
• Check interpolation: Easy to get wrong
• Test stiff problems: If implementing stiff solvers
• Benchmark early: Performance problems easier to fix early

Getting Help

Resources

1. Julia's OrdinaryDiffEq.jl: Reference implementation

   • Location: /tmp/diffeq_copy/OrdinaryDiffEq.jl/
   • Well-tested, can compare behavior

2. Hairer & Wanner textbooks:

   • "Solving ODEs I: Nonstiff Problems"
   • "Solving ODEs II: Stiff and DAE Problems"

3. DiffEqDevDocs: Developer documentation

   • https://docs.sciml.ai/DiffEqDevDocs/stable/

4. Test problems: Standard ODE test suite

   • Van der Pol, Robertson, Pleiades, etc.
   • Reference solutions available

Creating New Detailed Feature Files

When ready to work on a feature that only has a brief summary:

1. Copy structure from features/01-bs3-method.md
2. Fill in details from FEATURE_TEMPLATES.md
3. Add algorithm-specific information
4. Create comprehensive task checklist
5. Define specific test requirements
6. Estimate complexity honestly

Tracking Progress

In README.md

Update the checkboxes as features are completed:

• Incomplete
• Complete

Update completion statistics at bottom:

## Progress Tracking

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

Optional: Keep a CHANGELOG.md

Document major milestones:

# Changelog

## 2025-01-XX
- Completed BS3 method
- Completed PID controller
- Started Vern7 implementation

## 2025-01-YY
- Completed Vern7
- Linear solver infrastructure in progress

Questions to Ask Before Starting

Before implementing a feature:

1. Do I understand the algorithm?

   • Read the papers
   • Understand the math
   • Know the use cases

2. Are dependencies satisfied?

   • Check the dependency list
   • Make sure infrastructure exists

3. Do I have test cases ready?

   • Know how to verify correctness
   • Have reference solutions

4. What's the success criteria?

   • Clear definition of "done"
   • Performance targets

Next Steps

1. Read README.md to see the full roadmap
2. Pick a feature to start with (suggest: BS3 or PID Controller)
3. Read its detailed feature file
4. Implement following the task checklist
5. Test thoroughly
6. Update the roadmap
7. Move to next feature!

Good luck! You're building something great. 🚀