Finished bs3 (at least for now)

benches/README.md

@@ -0,0 +1,112 @@
+# Benchmarks
+
+This directory contains performance benchmarks for the ODE solver library.
+
+## Running Benchmarks
+
+To run all benchmarks:
+```bash
+cargo bench
+```
+
+To run a specific benchmark file:
+```bash
+cargo bench --bench bs3_vs_dp5
+cargo bench --bench simple_1d
+cargo bench --bench orbit
+```
+
+## Benchmark Suites
+
+### `bs3_vs_dp5.rs` - BS3 vs DP5 Comparison
+
+Comprehensive performance comparison between the Bogacki-Shampine 3(2) method (BS3) and Dormand-Prince 4(5) method (DP5).
+
+**Test Problems:**
+1. **Exponential Decay** - Simple 1D problem: `y' = -0.5*y`
+2. **Harmonic Oscillator** - 2D conservative system: `y'' + y = 0`
+3. **Nonlinear Pendulum** - Nonlinear 2D system with trigonometric terms
+4. **Orbital Mechanics** - 6D system with gravitational dynamics
+5. **Interpolation** - Performance of dense output interpolation
+6. **Tolerance Scaling** - How methods perform across tolerance ranges (1e-3 to 1e-7)
+
+**Expected Results:**
+- **BS3** should be faster for moderate tolerances (1e-3 to 1e-6) on simple problems
+  - Lower overhead: 4 stages vs 7 stages for DP5
+  - FSAL property: effective cost ~3 function evaluations per step
+- **DP5** should be faster for tight tolerances (< 1e-7)
+  - Higher order allows larger steps
+  - Better for problems requiring high accuracy
+- **Interpolation**: DP5 has more sophisticated interpolation, may be faster/more accurate
+
+### `simple_1d.rs` - Simple 1D Problem
+
+Basic benchmark for a simple 1D exponential decay problem using DP5.
+
+### `orbit.rs` - Orbital Mechanics
+
+6D orbital mechanics problem using DP5.
+
+## Benchmark Results Interpretation
+
+Criterion outputs timing statistics for each benchmark:
+- **Time**: Mean execution time with confidence interval
+- **Outliers**: Number of measurements significantly different from the mean
+- **Plots**: Stored in `target/criterion/` (if gnuplot is available)
+
+### Performance Comparison
+
+When comparing BS3 vs DP5:
+
+1. **For moderate accuracy (tol ~ 1e-5)**:
+   - BS3 typically uses ~1.5-2x the time per problem
+   - But this can vary by problem characteristics
+
+2. **For high accuracy (tol ~ 1e-7)**:
+   - DP5 becomes more competitive or faster
+   - Higher order allows fewer steps
+
+3. **Memory usage**:
+   - BS3: Stores 4 values for dense output [y0, y1, f0, f1]
+   - DP5: Stores 5 values for dense output [rcont1..rcont5]
+   - Difference is minimal for most problems
+
+## Notes
+
+- Benchmarks use `std::hint::black_box()` to prevent compiler optimizations
+- Each benchmark runs multiple iterations to get statistically significant results
+- Results may vary based on:
+  - System load
+  - CPU frequency scaling
+  - Compiler optimizations
+  - Problem characteristics (stiffness, nonlinearity, dimension)
+
+## Adding New Benchmarks
+
+To add a new benchmark:
+
+1. Create a new file in `benches/` (e.g., `my_benchmark.rs`)
+2. Add benchmark configuration to `Cargo.toml`:
+   ```toml
+   [[bench]]
+   name = "my_benchmark"
+   harness = false
+   ```
+3. Use the Criterion framework:
+   ```rust
+   use criterion::{criterion_group, criterion_main, Criterion};
+   use std::hint::black_box;
+
+   fn my_bench(c: &mut Criterion) {
+       c.bench_function("my_test", |b| {
+           b.iter(|| {
+               black_box({
+                   // Code to benchmark
+               });
+           });
+       });
+   }
+
+   criterion_group!(benches, my_bench);
+   criterion_main!(benches);
+   ```