# 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);
   ```